Skip to content
PT Start free

// docs

Google: Find places and businesses

Extracts locations from Google Maps by keyword and reference address.

google.com:places · 1 credit per request

Standard credit cost. Your account pricing is shown in the sandbox.

Try this operation in the sandbox

HTTP request

cURL 
curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

google_com_places · tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "google_com_places",
    "arguments": {
      "keyword": "coffee",
      "address": "Rua XV de Novembro, 160, Curitiba, PR",
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

FieldTypeRequirementRuleDefaultExample
url
URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields.
 string (URL) Optional Optional; when absent, the gateway mounts the canonical search URL. - https://www.google.com/maps/search/?api=1&query=coffee+curitiba+pr
keyword
Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.
 string Required Mandatory to define the type of location searched. - coffee
address
Reference address used by Google Places to locate the search area.
 string Required Required to define the search area on Google Maps. - Rua XV de Novembro, 160, Curitiba, PR
target
Target source for extraction.
 enum Required Always mandatory in the payload and must be google.com. - google.com
type
Extraction type: pdp, idp, plp, ilp, quote, review or places.
 enum Required Always mandatory in the payload and must be places. - places

Request examples

Places by keyword + address

Recommended flow; the gateway mounts the canonical URL automatically.

Places by keyword + address 
{
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}

Places with optional URL

URL can be sent for traceability, keeping keyword and address mandatory.

Places with optional URL 
{
  "url": "https://www.google.com/maps/search/?api=1&query=coffee+curitiba+pr",
  "keyword": "coffee",
  "address": "Rua XV de Novembro, 160, Curitiba, PR",
  "target": "google.com",
  "type": "places"
}

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

responseSchema 
{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.searchAreaUrl": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.keyword": "string",
  "data.address": "string",
  "data.searchRadiusMeters": "number",
  "data.center.latitude": "number",
  "data.center.longitude": "number",
  "data.totalResults": "number",
  "data.items[].id": "string",
  "data.items[].placeId": "string",
  "data.items[].url": "string",
  "data.items[].name": "string",
  "data.items[].address": "string",
  "data.items[].website": "string",
  "data.items[].domain": "string",
  "data.items[].phone": "string",
  "data.items[].city": "string",
  "data.items[].country": "string",
  "data.items[].plusCode": "string",
  "data.items[].latitude": "number",
  "data.items[].longitude": "number",
  "data.items[].reviewScore": "number",
  "data.items[].reviewCount": "number",
  "data.items[].categories[]": "string",
  "data.items[].price": "string"
}

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

responseExample 
{
  "requestId": "77777777-1111-4111-8111-777777777777",
  "executionId": "77777777-2222-4222-8222-777777777777",
  "data": {
    "source": "google.com",
    "type": "places",
    "url": "https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR",
    "searchAreaUrl": "https://www.google.com/search?tbm=map&hl=en&gl=us&q=Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR",
    "requestUrl": "https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR",
    "extractedAt": "2026-02-17T20:10:00.000Z",
    "keyword": "coffee",
    "address": "Rua XV de Novembro, 160, Curitiba, PR",
    "searchRadiusMeters": 23420.81,
    "center": {
      "latitude": -25.4314,
      "longitude": -49.2721
    },
    "totalResults": 2,
    "items": [
      {
        "id": "0x94dce444ecd9879d:0xb967f191d1ba09ae",
        "placeId": "ChIJnYfZ7ETk3JQRrgm60ZHxZ7k",
        "url": "https://www.google.com/maps?cid=13363945260079319470",
        "name": "Le Caffes Especiais",
        "address": "Av. Sete de Setembro, 1865 - Centro, Curitiba - PR, 80060-070, Brazil",
        "website": "https://www.lecaffes.com.br/",
        "domain": "www.lecaffes.com.br",
        "phone": "+55 41 99999-9999",
        "city": "Curitiba",
        "country": "Brazil",
        "plusCode": "CWC8+R2",
        "latitude": -25.4348,
        "longitude": -49.2569,
        "reviewScore": 4.9,
        "reviewCount": 154,
        "categories": [
          "Coffee shop",
          "Cafe"
        ],
        "price": "$$"
      },
      {
        "id": "0x94dce5a3b5597ef7:0x929e384097106510",
        "placeId": "ChIJ9345taPl3JQREGUQl0A4npI",
        "url": "https://www.google.com/maps?cid=10569206864830616848",
        "name": "Space Cat Coffee",
        "address": "R. Dr. Generoso Borges, 365 - Batel, Curitiba - PR, 80410-010, Brazil",
        "website": "https://spacecatcoffee.com.br/",
        "domain": "spacecatcoffee.com.br",
        "phone": "+55 41 98888-8888",
        "city": "Curitiba",
        "country": "Brazil",
        "plusCode": "CWG5+6V",
        "latitude": -25.4399,
        "longitude": -49.2852,
        "reviewScore": 4.8,
        "reviewCount": 231,
        "categories": [
          "Coffee shop"
        ],
        "price": "$$"
      }
    ]
  }
}

Complete field reference

PathTypeDescriptionExample
data.address string Field data.address returned in the response payload. Rua XV de Novembro, 160, Curitiba, PR
data.center.latitude number Field data.center.latitude returned in the response payload. -25.4314
data.center.longitude number Field data.center.longitude returned in the response payload. -49.2721
data.extractedAt string (iso datetime) data.extractedAt field returned in the response payload. 2026-02-17T20:10:00.000Z
data.items[].address string Field data.items[].address returned in the response payload. Av. Sete de Setembro, 1865 - Centro, Curitiba - PR, 80060-070, Brazil
data.items[].categories[] string data.items[].categories[] field returned in the response payload. Coffee shop
data.items[].city string Field data.items[].city returned in the response payload. Curitiba
data.items[].country string Field data.items[].country returned in the response payload. Brazil
data.items[].domain string Field data.items[].domain returned in the response payload. www.lecaffes.com.br
data.items[].id string Field data.items[].id returned in the response payload. 0x94dce444ecd9879d:0xb967f191d1ba09ae
data.items[].latitude number Field data.items[].latitude returned in the response payload. -25.4348
data.items[].longitude number Field data.items[].longitude returned in the response payload. -49.2569
data.items[].name string data.items[].name field returned in the response payload. Le Caffes Especiais
data.items[].phone string Field data.items[].phone returned in the response payload. +55 41 99999-9999
data.items[].placeId string data.items[].placeId field returned in the response payload. ChIJnYfZ7ETk3JQRrgm60ZHxZ7k
data.items[].plusCode string data.items[].plusCode field returned in the response payload. CWC8+R2
data.items[].price string Field data.items[].price returned in the response payload. $$
data.items[].reviewCount number Field data.items[].reviewCount returned in the response payload. 154
data.items[].reviewScore number Field data.items[].reviewScore returned in the response payload. 4.9
data.items[].url string data.items[].url field returned in the response payload. https://www.google.com/maps?cid=13363945260079319470
data.items[].website string Field data.items[].website returned in the response payload. https://www.lecaffes.com.br/
data.keyword string Field data.keyword returned in the response payload. coffee
data.requestUrl string Same value as `data.url`; never exposes the queried internal endpoint. https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR
data.searchAreaUrl string data.searchAreaUrl field returned in the response payload. https://www.google.com/search?tbm=map&hl=en&gl=us&q=Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR
data.searchRadiusMeters number Field data.searchRadiusMeters returned in the response payload. 23420.81
data.source string Field data.source returned in the response payload. google.com
data.totalResults number Field data.totalResults returned in the response payload. 2
data.type string Field data.type returned in the response payload. places
data.url string Field data.url returned in the response payload. https://www.google.com/maps/search/?api=1&query=coffee+Rua+XV+de+Novembro%2C+160%2C+Curitiba%2C+PR
executionId string (uuid) Field executionId returned in the response payload. 77777777-2222-4222-8222-777777777777
notFound boolean (optional; true when the upstream entity was not found and data is null) Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully. N/A
requestId string (uuid) Field requestId returned in the response payload. 77777777-1111-4111-8111-777777777777

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP statusError codeMeaning
400INVALID_PAYLOADInvalid JSON or a request that violates the documented validation rules.
401UNAUTHORIZEDMissing authorization or an invalid API key or token.
402INSUFFICIENT_CREDITSThe account has insufficient credits for this operation.
403FORBIDDENThe account does not have access, or the API is temporarily disabled.
409EXECUTION_CONFLICTThe execution identifier conflicts with an incompatible execution state.
429RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTSA rate limit or simultaneous request limit was exceeded.
5xxUPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERRORAn upstream, worker or gateway failure. Failed requests follow the platform refund policy.

Other Google operations