Google Maps tools

Local search results, business profiles, and prospect lists.

3 tools are implemented in this family. The definitions below come from the service’s actual tool catalog.

Authenticate, inspect the schema, then request an estimate using dry_run where supported. Research can spend workspace credits.

Search Google Maps

maps_search_places

The places Google Maps shows for a search in an area, in Maps' order: local competitor checks and spot-checking a ranking at one point. Rankings change street to street, so for a rank grid call it once per point with latitude, longitude and zoom. For a filtered list of businesses use maps_search_businesses; for one full profile use maps_get_place. Returns rows[] in Maps' order: rank, place_id, cid, name, category, address, phone, website and domain (null when the profile lists no website), rating (stars out of 5), reviews, is_claimed, status (open or closed by opening hours when Google was read, not whether it trades; temporarily_closed and closed_forever are the business's own state), maps_url, latitude, longitude. Cost: 1 credit. Cached 24 hours.

REST endpoint

POST /api/maps/tools/maps_search_places

Product-credit cost

1 credit. Cached 24 hours.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 700,
      "description": "Required. The search, e.g. \"emergency plumber\"."
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code, e.g. \"Austin,Texas,United States\". Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "latitude": {
      "description": "Search around this point instead of location. Give longitude too.",
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "description": "Used with latitude.",
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "zoom": {
      "default": 14,
      "description": "Map zoom at the point: 14 is about a neighbourhood, 11 about a city. Default 14.",
      "type": "integer",
      "minimum": 3,
      "maximum": 21
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "depth": {
      "default": 20,
      "description": "Places to fetch. Default 20, max 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keyword"
  ]
}

Find businesses in an area

maps_search_businesses

Businesses within a radius of a point, filtered by category, name, rating, review count or claimed status: prospect lists and counting a category in an area. Not ranked unless order_by is set. For what Maps shows a searcher use maps_search_places. Returns rows[]: place_id, cid, name, category, address, phone, website and domain (null when the profile lists no website), rating (stars out of 5), reviews, is_claimed, status (open or closed by opening hours when Google was read, not whether it trades; temporarily_closed and closed_forever are the business's own state), maps_url, latitude, longitude. A null website marks a business without one. meta.rows_available is the number of matching businesses. Cost: 4 + 12 per 100 rows. Default 100 rows = 16 credits. Cached 7 days.

REST endpoint

POST /api/maps/tools/maps_search_businesses

Product-credit cost

4 + 12 per 100 rows. Default 100 rows = 16 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90,
      "description": "Required. Centre of the search area."
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180,
      "description": "Required."
    },
    "radius_km": {
      "default": 5,
      "description": "Default 5, max 1000.",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000
    },
    "categories": {
      "description": "Google category ids in snake case, e.g. dentist or pizza_restaurant. At most 10.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z0-9_]+$"
      }
    },
    "name": {
      "description": "Text the business name must contain.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "claimed": {
      "description": "true: owner-verified profiles only. false: unclaimed profiles only.",
      "type": "boolean"
    },
    "min_rating": {
      "type": "number",
      "minimum": 0,
      "maximum": 5
    },
    "max_rating": {
      "type": "number",
      "minimum": 0,
      "maximum": 5
    },
    "min_reviews": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_reviews": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "order_by": {
      "description": "Highest first. Unsorted when omitted.",
      "type": "string",
      "enum": [
        "rating",
        "reviews"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "latitude",
    "longitude"
  ]
}

Get a Google Business Profile

maps_get_place

One business's full Google Business Profile: categories, hours, description, rating breakdown and the topics its reviews mention. It does not find businesses or rivals; use the search tools for that. Returns place_id, cid, name, category, address, phone, website and domain (null when the profile lists no website), rating (stars out of 5), reviews, is_claimed, status (open or closed by opening hours when Google was read, not whether it trades; temporarily_closed and closed_forever are the business's own state), maps_url, latitude, longitude, additional_categories[], description, rating_counts[] (per star, starting at 1 star), hours[] (day, open, close as HH:MM; a day with no entry is closed), attributes[], topics[] (topic, mentions), services[], people_also_search[], book_online_url. Review text is not returned. NoData when Google has no profile for the lookup. Cost: 2 credits. Cached 7 days.

REST endpoint

POST /api/maps/tools/maps_get_place

Product-credit cost

2 credits. Cached 7 days.

Input JSON schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "place_id": {
      "description": "From a maps_* row.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "cid": {
      "description": "From a maps_* row or the cid= value in a Google Maps link.",
      "type": "string",
      "pattern": "^\\d+$"
    },
    "name": {
      "description": "Business name with its town, looked up within location.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "location": {
      "default": "United States",
      "description": "Provider location name or code, e.g. \"Austin,Texas,United States\". Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  }
}