Google Maps Scraper SDK

The official TypeScript SDK for the G Maps Extractor Google Maps Scraper API.

Search Google Maps businesses, retrieve public place photos, and collect public reviews from Node.js with typed requests and responses.

Features

• Google Maps business and place search
• Public place photos and videos
• Public reviews with documented sorting
• TypeScript types for the API's original response fields
• ESM and CommonJS support
• Structured errors and request timeouts
• No runtime dependencies

Install

npm install google-maps-scraper-sdk

Node.js 18 or newer is required.

Get an API key

Create an API key in the G Maps Extractor API dashboard. Free monthly requests are available, with higher-volume plans on the API pricing page.

Keep the key in an environment variable:

export GMAPS_EXTRACTOR_API_KEY="your-api-key"

This SDK is intended for server-side Node.js. Do not expose API keys in browser code.

Quick start

import { GoogleMapsScraperClient } from 'google-maps-scraper-sdk'

const client = new GoogleMapsScraperClient({
  apiKey: process.env.GMAPS_EXTRACTOR_API_KEY!,
})

const result = await client.search({
  q: 'coffee shops in Portland',
  ll: '@45.523064,-122.676483,11z',
  hl: 'en',
  gl: 'us',
  extra: true,
})

for (const place of result.data) {
  console.log(place.Name, place['Average Rating'], place.Website)
}

CommonJS is also supported:

const { GoogleMapsScraperClient } = require('google-maps-scraper-sdk')

Search businesses

const result = await client.search({
  q: 'design agency in New York',
  page: 1,
  ll: '@40.6970194,-74.3093048,11z',
  hl: 'en',
  gl: 'us',
  extra: true,
})

q and ll are required. ll uses the Google Maps coordinate format @latitude,longitude,zoom, such as @40.6970194,-74.3093048,11z. page defaults to 1 and accepts values from 1 to 10. Each page can contain up to 20 results. Set extra to true to request emails and social media links.

The SDK preserves API field names exactly:

const place = result.data[0]

console.log(place?.Name)
console.log(place?.['Review Count'])
console.log(place?.['Google Maps URL'])
console.log(place?.emails)

Retrieve photos

Use the Fid returned by a search:

const photos = await client.photos({
  fid: '0x89b7b0fbf994f971:0xccd1567c352422cf',
  page: 1,
})

for (const media of photos.photos) {
  console.log(media.photoUrl ?? media.videoUrl)
}

See the Google Maps Photos Scraper API for product details.

Retrieve reviews

import { ReviewSort } from 'google-maps-scraper-sdk'

const reviews = await client.reviews({
  fid: '0x89b7b0fbf994f971:0xccd1567c352422cf',
  page: 1,
  sort_by: ReviewSort.NEWEST,
})

for (const review of reviews.reviews) {
  console.log(review.rate, review.comment)
}

Available sort values are RELEVANT, NEWEST, HIGHEST_RATING, and LOWEST_RATING. See the Google Maps Reviews Scraper API for more use cases.

Errors and timeouts

import {
  GoogleMapsScraperClient,
  GoogleMapsScraperError,
} from 'google-maps-scraper-sdk'

const client = new GoogleMapsScraperClient({
  apiKey: process.env.GMAPS_EXTRACTOR_API_KEY!,
  timeoutMs: 60_000,
})

try {
  await client.search({
    q: 'restaurants in Austin',
    ll: '@30.3074624,-98.0335911,10z',
  })
} catch (error) {
  if (error instanceof GoogleMapsScraperError) {
    console.error(error.status, error.message, error.response)
  }
}

The SDK does not retry automatically because every API request may consume account usage.

Client options

| Option | Type | Default | Description | | --- | --- | --- | --- | | apiKey | string | Required | G Maps Extractor API key | | baseUrl | string | https://cloud.gmapsextractor.com/api | API base URL | | timeoutMs | number | 60000 | Request timeout in milliseconds | | fetch | typeof fetch | Node global fetch | Custom fetch implementation, useful for testing |

API reference

• Postman API documentation
• Google Maps Scraper API
• Google Maps Reviews Scraper API
• Google Maps Photos Scraper API
• API pricing

Development

npm install
npm run check

npm run check runs type checking, unit tests, dual-module build validation, and an npm package dry run.

Publishing

To publish a release manually:

npm login
npm publish --access public

Then configure npm Trusted Publishing for:

• GitHub owner: GMapsExtractor
• Repository: Google-Maps-Scraper-SDK
• Workflow: publish.yml

Future releases:

npm version patch
git push origin main --follow-tags

The v* tag triggers the GitHub Actions publishing workflow using OIDC. No long-lived npm token is required.

License

MIT