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

$3

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

``bash
npm install serpapi


or if you prefer yarn


yarn add serpapi
`

`js
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"]);
});
`

$3

- 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:

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

`js
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);
`

$3

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

`ts
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.

`js
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
`

$3

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:

`bash
npm install https-proxy-agent


or if you prefer yarn


yarn add https-proxy-agent
`

Then use it in your code:

`js
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

$3

Get a JSON response based on search parameters.

#### Parameters

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

#### Examples

`javascript
// 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);
`

$3

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

`javascript
// 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);
`

$3

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

`javascript
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);
`

$3

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

`javascript
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);
`

$3

Get account information of an API key.

#### Parameters

- parameters
object
(optional, default {})

- parameters.api_key
string?
API key
- parameters.timeout
number?
timeout in milliseconds
- callback fn? optional callback

#### Examples

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

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

$3

Get supported locations. Does not require an API key.


#### 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

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

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