Skip to content

New AI assistant answers: ChatGPT, Gemini, Copilot and AI Mode by API

SerpKite
Get API key
Docs menu / Google Maps

Google Maps

Google Maps search: places with address, coordinates, categories, rating, hours, phone, website and place_id, in any language.

POST https://api.serpkite.com/v1/maps Credits: 1 per page Try in playground
View as Markdown

Google Maps search: businesses and points of interest with full address, coordinates, categories, rating, review count, hours, phone, website and the IDs you need for /v1/place and /v1/reviews. Results come from Google Maps search data, so addresses, categories (type, types) and hours are in the request language, Russian included.

Where to search. ll (@lat,lng,zoomz, zoom 14z by default) searches the map at that point and zoom, wherever the request comes from. location (or uule) searches the named place. Without either, Google picks the area from the query (an exact name or address) or from where the request comes from, so pass location or ll for local queries such as "coffee".

Request body

Send a JSON object with Content-Type: application/json. The same parameters also work as a query string on GET /v1/maps. JSON arrays are rejected: to run many queries at once, use POST /v1/batches at half price. Unknown parameters return 400 invalid_request with a message that names the replacement; see strict validation.

ParameterTypeDefaultDescription
q requiredstringThe search query. Required. Up to 2,048 characters.
countrystringusCountry to search from, as a two-letter ISO code (us, gb, de, in…). Defaults to the country a location ends in.
languagestringenInterface language, as a language code with an optional region (en, de, pt-BR, zh-TW…).
locationstringCanonical location for local results, e.g. "Austin, Texas, United States". Ending in a country name also sets country.
uulestringGoogle-encoded location string. Use instead of location if you already have it.
llstringMaps and places: search the map at a point and zoom, as "@lat,lng,zoomz", e.g. "@52.52,13.40,14z" (zoom defaults to 14z), wherever the request comes from. Overrides location.
pageinteger1Results page, 1–10. Each page is billed separately.
enginestring or arraygoogleWhich search providers may answer. google is Google only (SerpKite still retries Google internally); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: google, auto, consensus, brave, bing, yahoo, duckduckgo, mojeek, wikipedia, yandex.
formatstringjsonResponse format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: json, compact, markdown.
fieldsstringComma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens.
max_ageintegerAccept a cached result up to this many seconds old. Cache hits cost 50% of the credits.

Example request

Authenticate with Authorization: Bearer $SERPKITE_API_KEY (GET requests may pass ?api_key= instead). The official SDKs read SERPKITE_API_KEY for you. See Authentication.

curl https://api.serpkite.com/v1/maps \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"coffee roasters","location":"Berlin, Germany"}'

Response fields

FieldTypeDescription
requestobjectThe normalised request, with defaults filled in: endpoint, engine, q, country, language, location, num, page, device, autocorrect…
results[]arrayposition, title, address, country (ISO code, upper case), latitude, longitude, timezone (IANA), rating, rating_count, price_level, type, types[], website, phone_number, international_phone_number, opening_hours, weekly_hours, description, thumbnail_url, google_maps_url, place_id, cid, fid (with engine=yandex: oid and yandex_maps_url instead of the Google IDs and URL). Fields the map doesn't show for a place are absent.
results[].opening_hoursobjectHours as Google displays them, keyed by English weekday, in language: {"Monday": "7:30 am–6 pm", "Sunday": "Closed"}.
results[].weekly_hoursobjectThe same hours as data: monday … sunday, each a list of {open, close} local times (HH:MM, 24-hour, in timezone). Closed is [], open 24 hours is [{"open":"00:00","close":"24:00"}], a midnight close is "24:00", and an interval past midnight has next_day: true (17:30–03:00). Days Google doesn't list are absent.
metaobjectrequest_id, credits_used, cached, cached_at, engine (the provider that answered), route (provider attempts, see Search providers), latency_ms, parse_quality (ok, partial, empty), resolved_urls, unresolved_links (results whose link is still a Google redirect); llm (provider, model, input_tokens, output_tokens) and warnings when an AI step ran or failed.

Every billed response also carries credit and latency headers (X-Credits-Used, X-Credits-Remaining, X-Request-Id…).

Example response

200 OK · illustrative
{
  "request": {
    "endpoint": "maps",
    "engine": "google",
    "q": "coffee roasters",
    "location": "Berlin, Germany",
    "language": "en"
  },
  "results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "Beispielstraße 1, 10115 Berlin",
      "latitude": 52.5321,
      "longitude": 13.3849,
      "rating": 4.7,
      "rating_count": 812,
      "price_level": "€€",
      "type": "Coffee roasters",
      "types": [
        "Coffee roasters",
        "Cafe"
      ],
      "website": "https://coffee.example.de",
      "phone_number": "030 0000000",
      "international_phone_number": "+49 30 0000000",
      "country": "DE",
      "timezone": "Europe/Berlin",
      "opening_hours": {
        "Monday": "8 am–6 pm",
        "Sunday": "10 am–5 pm"
      },
      "weekly_hours": {
        "monday": [
          {
            "open": "08:00",
            "close": "18:00"
          }
        ],
        "sunday": [
          {
            "open": "10:00",
            "close": "17:00"
          }
        ]
      },
      "google_maps_url": "https://maps.google.com/?cid=1234567890123456789",
      "place_id": "ChIJexample0000000000000",
      "cid": "1234567890123456789",
      "fid": "0x47a851e3f1234567:0x112210f4e4a5c315"
    }
  ],
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 1,
    "cached": false,
    "engine": "google",
    "latency_ms": 1034,
    "parse_quality": "ok",
    "resolved_urls": true
  }
}

Errors

Errors use one shape: {"error":{"code","message","request_id"}}. Errors are never billed. Full list in Errors.

StatusCodeMeaning
400invalid_requestA parameter is missing or invalid.
401unauthorizedThe API key is missing, invalid or revoked.
402insufficient_creditsYour balance is too low. Buy a pack or wait for the monthly free grant.
429rate_limitedToo many requests per second for your plan. Retry after the Retry-After header.
503upstream_errorGoogle could not be fetched or parsed. Not billed; retry after Retry-After.

Notes

  • Pass place_id, cid or fid from a result to /v1/place for its full listing (description, photos) or to /v1/reviews for its reviews.
  • meta.parse_quality is partial when a place lacks a key field (title, coordinates) or a field looks wrong.