Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/serpapi/serpapi-javascript

Scrape and parse search engine results using SerpApi.
https://github.com/serpapi/serpapi-javascript
deno javascript json nodejs scraping serp-api serpapi typescript web-scraping-nodejs
Last synced: 2 months ago
JSON representation
Scrape and parse search engine results using SerpApi.
Host: GitHub
URL: https://github.com/serpapi/serpapi-javascript
Owner: serpapi
License: mit
Created: 2022-12-01T08:29:34.000Z (about 2 years ago)
Default Branch: master
Last Pushed: 2024-03-12T09:01:02.000Z (11 months ago)
Last Synced: 2024-11-17T19:45:19.563Z (2 months ago)
Topics: deno, javascript, json, nodejs, scraping, serp-api, serpapi, typescript, web-scraping-nodejs
Language: TypeScript
Homepage: https://serpapi.com
Size: 257 KB
Stars: 48
Watchers: 8
Forks: 5
Open Issues: 7
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

        # SerpApi for JavaScript/TypeScript

[![npm version](https://img.shields.io/npm/v/serpapi)](https://www.npmjs.com/package/serpapi)

[![Deno version](https://deno.land/badge/serpapi/version)](https://deno.land/x/serpapi)

[![Build status](https://github.com/serpapi/serpapi-javascript/workflows/Build/badge.svg?branch=master)](https://github.com/serpapi/serpapi-javascript/actions/workflows/build.yml)

[![License](https://img.shields.io/github/license/serpapi/serpapi-javascript)](https://github.com/serpapi/serpapi-javascript/blob/master/LICENSE)

[![SerpApi Libraries](https://img.shields.io/badge/SerpApi-Libraries-blue)](https://serpapi.com/integrations)

Scrape and parse search engine results using [SerpApi](https://serpapi.com). 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](https://github.com/serpapi/serpapi-javascript/blob/master/docs/migrating_from_google_search_results_nodejs.md) to find out how to upgrade. |

| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

## Quick start

### Node.js

- Supports Node.js 7.10.1 and newer.

- Refer to

  [this example](https://github.com/serpapi/serpapi-javascript/tree/master/examples/node/js_node_7_up)

  for help.

```bash

npm install 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"]);

});

```

### 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](https://github.com/serpapi/serpapi-javascript/tree/master/examples/node/js_node_14_up)

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

```

### Deno

- Import directly from deno.land.

- Usage is otherwise the same as above.

- Refer to

  [this example](https://github.com/serpapi/serpapi-javascript/tree/master/examples/deno)

  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](https://www.npmjs.com/package/serpapi) and

  [Deno](https://deno.land/x/serpapi).

- Promises and async/await support.

- Callbacks support.

- [Examples in JavaScript/TypeScript on Node.js/Deno using ESM/CommonJS, and more](https://github.com/serpapi/serpapi-javascript/tree/master/examples).

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

```

## Pagination

Built-in pagination is not supported. Please refer to our pagination examples

for a manual approach:

- [Pagination example (Node.js >= 7)](https://github.com/serpapi/serpapi-javascript/tree/master/examples/node/js_node_7_up/pagination_example.js)

- [Pagination example (Node.js >= 14)](https://github.com/serpapi/serpapi-javascript/tree/master/examples/node/js_node_14_up/pagination_example.js)

- [Pagination example (Deno)](https://github.com/serpapi/serpapi-javascript/tree/master/examples/deno/pagination_example.ts)

## Functions

#### Table of Contents

- [getJson](#getjson)

  - [Parameters](#parameters)

  - [Examples](#examples)

- [getHtml](#gethtml)

  - [Parameters](#parameters-1)

  - [Examples](#examples-1)

- [getJsonBySearchId](#getjsonbysearchid)

  - [Parameters](#parameters-2)

  - [Examples](#examples-2)

- [getHtmlBySearchId](#gethtmlbysearchid)

  - [Parameters](#parameters-3)

  - [Examples](#examples-3)

- [getAccount](#getaccount)

  - [Parameters](#parameters-4)

  - [Examples](#examples-4)

- [getLocations](#getlocations)

  - [Parameters](#parameters-5)

  - [Examples](#examples-5)

### getJson

Get a JSON response based on search parameters.

#### Parameters

- `parameters`

  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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);

```

### 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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);

```

### 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**

  search ID

- `parameters`

  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**

  (optional, default `{}`)

  - `parameters.api_key`

    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**

    API key

  - `parameters.timeout`

    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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);

```

### 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**

  search ID

- `parameters`

  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**

  (optional, default `{}`)

  - `parameters.api_key`

    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**

    API key

  - `parameters.timeout`

    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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);

```

### getAccount

Get account information of an API key. 

#### Parameters

- `parameters`

  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**

  (optional, default `{}`)

  - `parameters.api_key`

    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**

    API key

  - `parameters.timeout`

    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/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);

```

### getLocations

Get supported locations. Does not require an API key.

#### Parameters

- `parameters`

  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**

  (optional, default `{}`)

  - `parameters.q`

    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**

    query for a location

  - `parameters.limit`

    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?**

    limit on number of locations returned

  - `parameters.timeout`

    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?**

    timeout in milliseconds

- `callback` **fn?** optional callback

#### Examples

```javascript

// async/await

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

// callback

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

```