serpapi

SerpApi for JavaScript/TypeScript

Scrape and parse search engine results using SerpApi. Get search results from Google, Bing, Baidu, Yandex, Yahoo, Home Depot, eBay and more.

🪧 Coming from google-search-results-nodejs? Check out the migration document to find out how to upgrade.

Quick start

Node.js

• Supports Node.js 7.10.1 and newer.
• Refer to this example for help.

npm install serpapi
# or if you prefer yarn
yarn add serpapi

const { getJson } = require("serpapi");
getJson({
  engine: "google",
  api_key: API_KEY, // Get your API_KEY from https://serpapi.com/manage-api-key
  q: "coffee",
  location: "Austin, Texas",
}, (json) => {
  console.log(json["organic_results"]);
});

Node.js with ES Modules (ESM) and top-level await

• If you prefer using the import syntax and top-level await, you need to use at least Node.js 14.8.0.
• Refer to this example for help.

You will need to add "type": "module" to your package.json:

{
  "type": "module",
  // rest of package.json
}

import { getJson } from "serpapi";
const response = await getJson({
  engine: "google",
  api_key: API_KEY, // Get your API_KEY from https://serpapi.com/manage-api-key
  q: "coffee",
  location: "Austin, Texas",
});
console.log(response);

Deno

• Import directly from deno.land.
• Usage is otherwise the same as above.
• Refer to this example for help.

import { getJson } from "https://deno.land/x/serpapi/mod.ts";
const response = await getJson({
  engine: "google",
  api_key: API_KEY, // Get your API_KEY from https://serpapi.com/manage-api-key
  q: "coffee",
  location: "Austin, Texas",
});
console.log(response);

Features

• TypeScript support.
• Works out-of-the-box with Node.js and Deno.
• Promises and async/await support.
• Callbacks support.
• Examples in JavaScript/TypeScript on Node.js/Deno using ESM/CommonJS, and more.

Configuration

You can declare a global api_key and timeout value by modifying the config object. timeout is defined in milliseconds and defaults to 60 seconds.

All functions, other than getLocations, accepts an optional api_key and timeout that will take precedence over the values defined in config.

getLocations doesn't require an API key.

import { config, getJson } from "serpapi";

config.api_key = API_KEY;
config.timeout = 60000;

await getJson({ engine: "google", q: "coffee" }); // uses the API key defined in the config
await getJson({ engine: "google", api_key: API_KEY_2, q: "coffee" }); // API_KEY_2 will be used

Using a Proxy

You can use a proxy by passing requestOptions with an HttpsProxyAgent instance. This can be done either globally through the config object or per-request in the parameters.

First, install the required package:

npm install https-proxy-agent
# or if you prefer yarn
yarn add https-proxy-agent

Then use it in your code:

import { config, getJson } from "serpapi";
import { HttpsProxyAgent } from "https-proxy-agent";

// Global configuration
config.requestOptions = {
  agent: new HttpsProxyAgent("http://proxy-server:port"),
};

// Or per-request configuration
await getJson({
  engine: "google",
  q: "coffee",
  requestOptions: {
    agent: new HttpsProxyAgent("http://proxy-server:port"),
  },
});

Pagination

Built-in pagination is not supported. Please refer to our pagination examples for a manual approach:

• Pagination example (Node.js >= 7)
• Pagination example (Node.js >= 14)
• Pagination example (Deno)

Functions

Table of Contents

• getJson
  • Parameters
  • Examples
• getHtml
  • Parameters
  • Examples
• getJsonBySearchId
  • Parameters
  • Examples
• getHtmlBySearchId
  • Parameters
  • Examples
• getAccount
  • Parameters
  • Examples
• getLocations
  • Parameters
  • Examples

getJson

Get a JSON response based on search parameters.

Parameters

• parameters object search query parameters for the engine
• callback fn? optional callback

Examples

// single call (async/await)
const json = await getJson({ engine: "google", api_key: API_KEY, q: "coffee" });

// single call (callback)
getJson({ engine: "google", api_key: API_KEY, q: "coffee" }, console.log);

getHtml

Get a HTML response based on search parameters.

• Accepts an optional callback.
• Responds with a JSON string if the search request hasn't completed.

Parameters

• parameters object search query parameters for the engine
• callback fn? optional callback

Examples

// async/await
const html = await getHtml({ engine: "google", api_key: API_KEY, q: "coffee" });

// callback
getHtml({ engine: "google", api_key: API_KEY, q: "coffee" }, console.log);

getJsonBySearchId

Get a JSON response given a search ID.

• This search ID can be obtained from the search_metadata.id key in the response.
• Typically used together with the async parameter.
• Accepts an optional callback.

Parameters

• searchId string search ID

• parameters object (optional, default {})

  • parameters.api_key string? API key
  • parameters.timeout number? timeout in milliseconds

• callback fn? optional callback

Examples

const response = await getJson({
  engine: "google",
  api_key: API_KEY,
  async: true,
  q: "coffee",
});
const { id } = response.search_metadata;
await delay(1000); // wait for the request to be processed.

// async/await
const json = await getJsonBySearchId(id, { api_key: API_KEY });

// callback
getJsonBySearchId(id, { api_key: API_KEY }, console.log);

getHtmlBySearchId

Get a HTML response given a search ID.

• This search ID can be obtained from the search_metadata.id key in the response.
• Typically used together with the async parameter.
• Accepts an optional callback.
• Responds with a JSON if the search request hasn't completed.

Parameters

• searchId string search ID

• parameters object (optional, default {})

  • parameters.api_key string? API key
  • parameters.timeout number? timeout in milliseconds

• callback fn? optional callback

Examples

const response = await getJson({
  engine: "google",
  api_key: API_KEY,
  async: true,
  q: "coffee",
});
const { id } = response.search_metadata;
await delay(1000); // wait for the request to be processed.

// async/await
const html = await getHtmlBySearchId(id, { api_key: API_KEY });

// callback
getHtmlBySearchId(id, { api_key: API_KEY }, console.log);

getAccount

Get account information of an API key. https://serpapi.com/account-api

Parameters

• parameters object (optional, default {})

  • parameters.api_key string? API key
  • parameters.timeout number? timeout in milliseconds

• callback fn? optional callback

Examples

// async/await
const info = await getAccount({ api_key: API_KEY });

// callback
getAccount({ api_key: API_KEY }, console.log);

getLocations

Get supported locations. Does not require an API key. https://serpapi.com/locations-api

Parameters

• parameters object (optional, default {})

  • parameters.q string? query for a location
  • parameters.limit number? limit on number of locations returned
  • parameters.timeout number? timeout in milliseconds

• callback fn? optional callback

Examples

// async/await
const locations = await getLocations({ limit: 3 });

// callback
getLocations({ limit: 3 }, console.log);