Docs / API reference

POST/v1/data/google/maps

Google Maps Search

Search Google Maps for businesses, places, and points of interest, or look up one place by place_id, CID, or data reference. Results include stable place identifiers, location, rating, aggregate review count, category, status, and source-dependent business details.

Execution model

Live request

Runtime depends on endpoint, target, pagination, rendering mode, and active plan limits.

Credit weight

Live catalog

Current weights are managed from the Data API Weights admin table and shown on pricing before use.

Google Maps Endpoint

Use text search, nearby search, or one-place lookup.

Getting Started

Send your API key as a bearer token. Start with the smallest request below.

Search Places

Send a place query and the number of results you need.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "ramen restaurants in Manhattan",
  "num_results": 10
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Search Modes

Nearby Search

Search around coordinates with a radius or zoom level.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "coordinates": "40.7580,-73.9855",
  "radius": 3000,
  "zoom": 14,
  "num_results": 20
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Place ID Lookup

Return one place from its Google Place ID.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4"
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

CID Lookup

Return one place from its permanent CID or Ludocid.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cid": "10325091291252938854"
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Data Reference Lookup

Use an encoded Google Maps data reference when that is the identifier you have.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "data": "!4m2!3m1!1s0x89c259af336b3341:0x1234567890abcdef"
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Filters

Filter and Sort Places

Narrow by type, keyword, rating, opening state, price, and sort order.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "restaurants",
  "type": "restaurant",
  "keyword": "vegetarian",
  "min_rating": 4.2,
  "open_now": true,
  "price_level": 2,
  "sort_by": "rating",
  "num_results": 25
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Locale and Reviews

Include Reviews

Localize results and include a bounded set of sorted reviews.

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "cafes in Chennai",
  "language": "en",
  "country": "in",
  "include_reviews": true,
  "reviews_limit": 5,
  "reviews_sort": "newest"
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com"
    }
  ]
}

Response

Use search_type to distinguish search, nearby, and place-detail results, then read places.

Error Handling

Handle 401 for authentication, 422 for invalid input, 429 for limits, and retry only transient failures.

Parameters

Name	Type	Requirement	Description
query	string	Optional	Search query (e.g. 'restaurants near Times Square'). Max 2048 characters.
coordinates	string	Optional	GPS coordinates as 'lat,lng' (e.g. '40.7580,-73.9855').
radius	number	Optional	Search radius in meters (100-50000). With coordinates, places outside the radius are removed.
zoom	number	Optional	Map zoom level (1-21). Auto-calculated from radius if not set.
type	string	Optional	Place type filter: restaurant, hotel, gas_station, hospital, cafe, bar, gym, pharmacy, bank, supermarket, park, museum, airport.
keyword	string	Optional	Additional keyword filter (max 500 chars). E.g. 'vegetarian', 'rooftop'.
min_rating	number	Optional	Minimum star rating filter (1.0-5.0).
open_now	boolean	Optional	Only show places that are currently open.
price_level	number	Optional	Price range filter: 1=$, 2=$$, 3=$$$, 4=$$$$.
sort_by	string	Optional	Sort order: "relevance", "distance", "rating", "reviews".
num_results	number	Optional	Maximum number of places to return (1-200). Actual results may be fewer.
place_id	string	Optional	Google Place ID for a detailed single-place lookup. You may also send query as a fallback label, e.g. place_id for Sydney Opera House.
cid	string	Optional	CID / Ludocid permanent business identifier.
data	string	Optional	Google Maps data parameter (encoded place reference).
language	string	Optional	Language code (hl parameter).
country	string	Optional	Google gl result-localization hint. This does not select or guarantee a proxy country.
include_reviews	boolean	Optional	Deprecated best-effort review enrichment for compatibility. Limited to 20 places; search success does not guarantee review cards.
reviews_limit	number	Optional	Deprecated best-effort review limit (1-20). Applies only when include_reviews=true.
reviews_sort	string	Optional	Deprecated best-effort review ordering. Only most_relevant is supported when include_reviews=true.

Response fields

Field	Type	Description
success	boolean	Whether Google Maps returned at least one matching place.
query	string	Original query when one was supplied.
coordinates_used	string	Coordinates used for nearby, radius, or distance processing.
search_type	string	Resolved mode: search, nearby, or place_details.
total_results	string	Number of places returned after filters. This can be lower than num_results.
filters_applied	object	Echo of filters that affected localization, selection, or sorting.
places[]	array	Ranked place records returned by Google Maps.
places[].title	string	Business or place name.
places[].place_id	string	Optional Google Place ID when exposed by the source.
places[].data_id	string	Optional Google hexadecimal place identifier used by place-specific data routes.
places[].data_cid	string	Optional decimal Google CID for the business listing.
places[].address	string	Optional formatted address when exposed by the source.
places[].gps_coordinates	object	Latitude and longitude when exposed by Google.
places[].rating	number	Aggregate Google star rating from 0 to 5 when available.
places[].review_count	number	Aggregate number of Google reviews when available. The legacy reviews field may contain the same count.
places[].type	string	Primary business or place category when available.
places[].website	string	Optional business website; commonly absent from search summaries.
places[].phone	string	Optional phone number when Google exposes it for the listing.
places[].price_level	number	Optional 1-4 price level for listings that publish pricing.
places[].working_hours	array	Optional weekly hours, usually available only from place details.
places[].description	string	Optional Google business description.
places[].google_maps_url	string	Direct Google Maps URL for the listing.
time_taken	number	Total endpoint processing time in seconds.
error	object	Structured failure details when success=false.
error.code	string	Stable failure class such as invalid_request, no_results, place_not_found, captcha, timeout, or upstream_unavailable.
error.message	string	Human-readable failure explanation.

Request and response

curl -X POST "https://api.datablue.dev/v1/data/google/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "coffee near Times Square",
  "coordinates": "40.7580,-73.9855",
  "radius": 3000,
  "num_results": 5,
  "min_rating": 4,
  "language": "en",
  "country": "us"
}'

Example response

{
  "success": true,
  "query": "coffee near Times Square",
  "coordinates_used": "40.7580,-73.9855",
  "search_type": "search",
  "total_results": "5",
  "time_taken": 3.42,
  "filters_applied": {
    "radius": 3000,
    "min_rating": 4,
    "country": "us"
  },
  "places": [
    {
      "position": 1,
      "title": "Culture Espresso",
      "place_id": "ChIJdTyxUaxZwokRNAyNj1mBu8A",
      "data_id": "0x89c259ac51b13c75:0xc0bb81598f8d0c34",
      "data_cid": "13887823103716256820",
      "address": "247 W 36th St, New York, NY 10018",
      "gps_coordinates": {
        "latitude": 40.7530781,
        "longitude": -73.9913242
      },
      "url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "google_maps_url": "https://www.google.com/maps/place/Culture+Espresso/...",
      "website": "https://www.cultureespresso.com",
      "phone": "(646) 438-9555",
      "rating": 4.6,
      "review_count": 531,
      "price": "$1-10",
      "price_level": 1,
      "type": "Coffee shop",
      "subtypes": [
        "Coffee shop",
        "Cafe"
      ],
      "open_state": "Open - Closes 7 PM",
      "open_now": true,
      "working_hours": [
        {
          "day": "Monday",
          "hours": "8 AM-7 PM"
        }
      ],
      "description": "Espresso drinks, pastries, and house-baked cookies.",
      "thumbnail": "https://lh5.googleusercontent.com/p/AF1QipN..."
    }
  ]
}