How to Integrate Exa.ai Semantic Search into Google Apps Script? [Tutorial]

4 min readOct 31, 2024

I’ve developed a client library that simplifies integrating Exa.ai’s semantic search capabilities into your Google Apps Script projects. This post provides a walkthrough of how to use the library.

What is Exa.ai?

Exa.ai is a semantic search engine that allows you to search for information based on meaning, not just keywords. This is particularly useful when you need to find information related to a concept rather than a specific phrase.

Library Features

This unofficial Exa.ai client for Google Apps Script offers:

Full Exa.ai API Compatibility: Access the full range of Exa.ai’s search functionality.
Familiar Interface: The library uses a structure similar to the official exa-js npm package, making it easier to transition between environments.
Seamless Google Apps Script Integration: Easily incorporate Exa.ai searches into your Google Sheets, Docs, or other Apps Script projects.
Support for all Exa.ai Search Types and Filters: Utilize different search types (neural, keyword, auto) and filters (category, date, domain).
Detailed Logging: Enable logging for debugging and monitoring API requests and responses.
Comprehensive Documentation and Examples: Clear documentation and examples to help you get started quickly.

Prerequisites

Before you begin, ensure you have the following:

Exa.ai Account and API Key: You can obtain an API key from Exa.ai.
Access to Google Apps Script: You can access Google Apps Script through script.google.com.

Getting Started

Here’s how to integrate the Exa.ai library into your Google Apps Script project:

Copy the Library: Copy the contents of the exa.gs file (here) into your Apps Script project.
Set Your API Key:

In your Apps Script project, navigate to File > Project settings > Script properties.
Add a new property with the following:
Name: EXA_API_KEY
Value: Your Exa.ai API key

Use the Library: You can now start using the library in your Apps Script functions.

Code Example: Basic News Search

function searchNews() {
  const exa = new Exa(PropertiesService.getScriptProperties().getProperty('EXA_API_KEY'));
  const results = exa.searchAndContents("Latest AI developments", {
    category: "news_article",
    numResults: 5
  });
  return results;
}

This simple example demonstrates how to search for the latest AI developments in news articles. The searchAndContents function returns an object containing the search results.

Creating an Exa Client

const exa = new Exa(apiKey);
exa.setLogging(true); // Optional: Enable debug logging

Search Methods

The primary search method is searchAndContents(query, options). This method retrieves search results including full text and summaries.

query (string): The search query string.
options (object): An object containing various search parameters (detailed below).

Available Search Options

The options object can include the following parameters:

type: “neural”, “keyword”, or “auto” (default: “neural”). Specifies the search type.
category: Filters results by category (e.g., “company”, “research_paper”, “news_article”). See full list in the code comments.
useAutoprompt: boolean (default: true). Whether to use Exa.ai’s autoprompt feature.
numResults: number (default: 10). The number of results to retrieve.
livecrawl: “always” or “fallback”. Specifies when to perform a live crawl.
includeDomains: string[]. An array of domains to include in the search.
excludeDomains: string[]. An array of domains to exclude from the search.
startPublishedDate: string (ISO format). Filters results by publish date.
endPublishedDate: string (ISO format). Filters results by publish date.
startCrawlDate: string (ISO format). Filters results by crawl date.
endCrawlDate: string (ISO format). Filters results by crawl date.
text: An object with options for retrieving text content (includeHtmlTags, maxCharacters).
highlights: An object for configuring highlights (query, numSentences, highlightsPerUrl).
summary: An object for configuring summaries (query).

Advanced Example: Company Search

function searchAICompanies() {
  const exa = new Exa(PropertiesService.getScriptProperties().getProperty('EXA_API_KEY'));
  
  return exa.searchAndContents(
    "innovative AI startups in natural language processing",
    {
      type: "neural",
      category: "company",
      numResults: 20,
      startPublishedDate: "2024-01-01T00:00:00.000Z",
      text: {
        maxCharacters: 1000
      },
      highlights: {
        query: "AI capabilities and innovations",
        numSentences: 2
      },
      summary: {
        query: "What are their main AI products and innovations?"
      }
    }
  );
}

This example shows a more complex search for AI startups, demonstrating the use of various filters and options for refining results.

8 Ideas of Integrations/Products Exa.ai + Google Apps Scripts

Some ideas on what you can build combining

@ExaAILabs with Google Workspace: research dashboards, smart docs assistant, meeting brief generator, form response enrichment, and more.

1. Research Dashboard in Google Sheets: Auto-updates daily with latest industry news and research for specified topics. Creates a summary table with key findings and source links.

2. Smart Document Assistant: Analyzes your Google Doc content in real-time and suggests relevant research papers, news articles, and sources in a sidebar.

3. Academic Literature Review Helper: Scans your research document and finds related academic papers, organizing them by relevance and creating citation drafts in a linked spreadsheet.

4. Meeting Brief Generator: Before calendar events, creates a brief with latest news and developments about the meeting participants’ companies and relevant industry updates.

5. Custom Google Form Response Enrichment: When someone submits a company name or topic in a form, automatically enriches the response with latest news, social media presence, and key information.

6. Smart Slides Research: While creating presentations, suggests relevant statistics, quotes, and sources based on your slide content through a sidebar.

7. Domain Expert Finder: Input a technical topic or problem, and get a spreadsheet of relevant experts, their recent work, and contact information found from personal websites and academic profiles.

8. Content Fact Checker: Analyzes your document content against recent reliable sources, highlighting claims that might need verification and suggesting supporting references.

Hope this library proves useful for integrating Exa.ai into your Google Apps Script projects. Please feel free to share any feedback or suggestions.