Skip to content

Google Maps

Overview

Method Endpoint Version Description
POST /api/v1/open/search v1 Google Search API endpoint for retrieving search results

Request Headers

Header Type Required Description
Content-Type string Yes Must be set to application/json
Accept string No Response format (defaults to application/json)

Authentication

API Key Authentication - Pass the API key as a request parameter: api_key=your_api_key - Example: "api_key": "your_api_key_here"

Request Example

curl -X POST "https://domain/api/v1/open/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key_here",
    // ...
  }'

Response Format

All responses follow a standardized JSON structure:

{
  "code": 200,
  "msg": "Success",
  "reqId": "req_1234567890",
  "timestamp": "2025-01-08T10:30:00Z",
  "data": {
    // Response data object
  }
}

HTTP Status Codes

Code Status Description Retry
200 OK Request successful No

Request Parameters

Parameter Type Required Description Default
api_key string Yes API key for authentication
engine string Yes Search engine type, currently engine value is google_maps google
q string Yes Search query, supports regular Google search syntax (like inurl:, site:, intitle:) and advanced search parameters
google_domain string No Google domain, defaults to google.com google.com
gl string No Search country code (e.g., us-United States, uk-United Kingdom, fr-France). Head to the Google countries page for a full list of supported Google countries.
hl string No Search language code (e.g., en-English, es-Spanish, fr-French). Head to the Google languages page for a full list of supported Google languages.
ll string No Parameter defines the GPS coordinates of the location where you want the search to originate from. Its value must match the following format: @ + latitude + , + longitude + , + zoom/map_height This will form a string that looks like this: e.g. @40.7455096,-74.0083012,14z or @43.8521864,11.2168835,10410m. The zoom attribute ranges from 3z, map completely zoomed out - to 21z, map completely zoomed in. Alternatively, you can specify map_height in meters (e.g., 10410m). The parameter should only be used when type is set to search. Parameter is required when using pagination. Results are not guaranteed to be within the requested geographic location.
data string No Parameter can be used to filter the search results. You can visit Google Maps website, set filters you want and simply copy the data value from their URL to SerpApi URL. One of the uses of the parameter is to search for a specific place; therefore, it is required if the type is set to place. Alternatively, place_id or data_cid can be used. To use the data parameter to search for a specific place, it needs to be constructed in the following sequence: !4m5!3m4!1s + data_id + !8m2!3d + latitude + !4d + longitude This will form a string that looks like this: !4m5!3m4!1s0x89c259b7abdd4769:0xc385876db174521a!8m2!3d40.750231!4d-74.004019. You can find the data_id using our Google Maps API.
start number No Parameter defines the result offset. It skips the given number of results. It's used for pagination. (e.g., 0 (default) is the first page of results, 10 is the 2nd page of results, 20 is the 3rd page of results, etc.).
place_id string No Parameter defines the unique reference to a place in Google Maps. Place IDs are available for most locations, including businesses, landmarks, parks, and intersections. You can find the place_id using our Google Maps API. You can read more about Place IDs here. place_id can be used without any other optional parameter. place_id and data_cid can't be used together. Parameter should not be confused with place_id in Google Search API and Google Local API which are the same as data_cid in Google Maps API.
safe string No Parameter defines the level of filtering for adult content. It can be set to active or off, by default Google will blur explicit content. off or active
data_cid string No Parameter defines the Google CID (customer identifier) of a place. This parameter can be found in Google Maps API local results, as well as in Google Search API and Google Local API local results under the name of place_id. You can also acquire it using Google's CID converter. data_cid can be used without any other optional parameter. data_cid and place_id can't be used together.
type string No Parameter defines the type of search you want to make. It can be set to: search - returns a list of results for the set q parameter, place - returns results for a specific place when data parameter is set Parameter is not required when using place_id or data_cid.
html string No Whether to return HTML format, 1-yes, 0-no 0

Response Example

{
    "code": 200,
    "data": {
        "search_metadata": {
            "raw_html_file": "oss_html",
            "total_time_taken": 2.032416469,
            "id": "1985902431212408832",
            "json_endpoint": "oss_json",
            "created_at": "2025-10-29 08:53:31",
            "processed_at": "2025-10-29 08:53:33",
            "google_url": "https://www.google.com/maps/search/coffee/",
            "status": "Success"
        },
        "search_information": {
          "organic_results_state": "Showing results for exact spelling despite spelling suggestion",
          "time_taken_displayed": 0.042
        },
        "search_parameters": {
            "engine": "google_maps",
            "html": "0",
            "google_domain": "www.google.com",
            "q": "coffee"
        },
        "local_results": [
          {
            "position": 1,
            "rating": "4.6",
            "price": "$1–10",
            "place_id": "sKvwaODNNKue4-EP6NzS2As",
            "gps_coordinates": {
              "latitude": 41.7915905,
              "longitude": -107.2158848
            },
            "title": "Deb B's Family Espresso",
            "type": "Coffee shop",
            "address": "1902 E Cedar StRawlins, WY 82301",
            "phone": "+1 307-324-2919",
            "hours": "Closed ⋅ Opens 5:45 AM",
            "data_id": "0x875d012260c53825:0xcfae46781ed48a9b",
            "data_cids": "14964976093526002331",
            "reviews_link": "https://search.google.com/local/reviews?placeid=ChIJJTjFYCIBXYcRm4rUHnhGrs8&q=coffee&authuser=0&hl=en&gl=US",
            "thumbnail": "https://lh3.googleusercontent.com/gps-cs-s/AC9h4noFm5HRSkAg2Ce3OlXFstWSlDrtxqIlm4AQPw0-NUNznm-roVqgihDUQh_2SnPfOEkJjZK0wCRaq5uiNrm_HctJ_Ni8GL_6L6T3LCm1ardYlDLS3wgun8NzqFI1cRhy8Ofiaj6c=w80-h92-k-no",
            "reviews": 229,
            "types": [
              "Coffee shop"
            ],
            "type_id": "Coffee shop",
            "type_ids": [
              "Coffee shop"
            ],
            "open_state": "Closed ⋅ Opens 5:45 AM",
            "operating_hours": {
              "Friday": "5:45 AM–5:30 PM",
              "Monday": "5:45 AM–5:30 PM",
              "Saturday": "8 AM–4 PM",
              "Sunday": "Closed",
              "Thursday": "5:45 AM–5:30 PM",
              "Tuesday": "5:45 AM–5:30 PM",
              "Wednesday": "5:45 AM–5:30 PM"
            },
            "website": "https://m.facebook.com/pages/category/Coffee-Shop/Deb-Bs-Family-Espresso-105017236208764/",
            "extensions": [
              {
                "service_options": [
                  "Drive-through",
                  "Onsite services"
                ]
              },
              {
                "highlights": [
                  "Great coffee",
                  "Great tea selection"
                ]
              },
              {
                "offerings": [
                  "Coffee"
                ]
              },
              {
                "dining_options": [
                  "Dessert"
                ]
              },
              {
                "atmosphere": [
                  "Casual"
                ]
              },
              {
                "crowd": [
                  "Tourists"
                ]
              },
              {
                "payments": [
                  "Credit cards",
                  "Debit cards"
                ]
              },
              {
                "children": [
                  "Good for kids"
                ]
              },
              {
                "parking": [
                  "Free parking lot",
                  "Free street parking"
                ]
              }
            ],
            "unsupported_extensions": [
              {
                "service_options": [
                  "Delivery"
                ]
              },
              {},
              {
                "dining_options": [
                  "Table service"
                ]
              },
              {},
              {
                "planning": [
                  "Accepts reservations"
                ]
              }
            ],
            "service_options": {
              "Delivery": true,
              "Drive-through": true
            },
            "order_online": "https://m.facebook.com/pages/category/Coffee-Shop/Deb-Bs-Family-Espresso-105017236208764/",
            "user_review": "Super cute, delicious coffees, friendly service!"
          }
        ]
    },
    "msg": "string",
    "reqId": "string"
}

Complete Response Parameters Overview

search_metadata

object Contains metadata about the search execution

Parameter Type Description Applicable Terminal
id string Unique identifier for the search request desktop
json_endpoint string Provide an interface endpoint for searching related JSON data, through which JSON-formatted search data can be obtained desktop
created_at string The timestamp when the search request was created, recording the time when the search was initiated desktop
processed_at string The timestamp when the search results were processed and became available for return, recording the time point from processing to completion of the search desktop
google_url string The Google search URL, which contains the search keyword "coffee" along with language parameters (hl=en for English), regional parameters (gl=us for the United States), and other search parameters, used to redirect to the corresponding Google search page desktop
status string Status of the search execution (e.g., Success) desktop
raw_html_file string Identifier for the original HTML file desktop
total_time_taken number The total time spent on the entire search process (including request sending, result parsing, and other stages) desktop

search_information

object Contains information about the search results

Parameter Type Description Applicable Terminal
organic_results_state string State of organic results desktop
time_taken_displayed number TDisplay time (i.e., the time spent on displaying the search results) desktop
query_displayed string Displayed query term, i.e., the actual keyword searched by the user in Google Maps desktop

search_parameters

object Contains the parameters used for the search

Parameter Type Description Applicable Terminal
q string Keywords used for this query desktop
engine string Search engine used for this query (e.g., google_web) desktop
html string When HTML=0, returns JSON; when HTML=1, returns HTML; when HTML=2, returns both JSON and HTML desktop
device string Device type used during search (e.g., desktop) desktop
google_domain string Specifies the corresponding Google domain (e.g., google.com, etc., used to distinguish Google services in different regions/locales) desktop

local_results

object[] Google Maps returns a collection of local places/services based on the user’s search query (e.g., hotel, restaurant, attraction).

Parameter Type Description Applicable Terminal
position number Ranking position in local search results desktop
rating string Rating of the place desktop
price string Price range description desktop
place_id string Unique identifier ID of a place in Google Maps desktop
gps_coordinates object Latitude and longitude coordinate information of the place desktop
gps_coordinates.latitude number Latitude value desktop
gps_coordinates.longitude number Longitude value desktop
title string Name of the place desktop
type string Type of place desktop
address string Address of the place desktop
phone string Contact phone number of the place desktop
hours string Brief description of the operating status of the place desktop
data_id string Internal data ID related to the place desktop
data_cids string Another internal identifier related to the place desktop
reviews_link string Link to the place’s review page desktop
thumbnail string Thumbnail image link of the place desktop
reviews number Number of reviews of the place desktop
types string[] Array form of place types desktop
type_id string Identifier of the place type desktop
type_ids string[] Array form of place type identifiers desktop
open_state string Detailed description of the operating status of the place desktop
operating_hours object Specific business hours of the place desktop
operating_hours.Friday string Friday business hours desktop
operating_hours.Monday string Monday business hours desktop
operating_hours.Saturday string Saturday business hours desktop
operating_hours.Sunday string Sunday business hours desktop
operating_hours.Thursday string Thursday business hours desktop
operating_hours.Tuesday string Tuesday business hours desktop
operating_hours.Wednesday string Wednesday business hours desktop
website string Official website link of the place desktop
extensions object[] Collection of extended information of the place desktop
extensions[].service_options string[] Service options list desktop
extensions[].highlights string[] List of place highlights desktop
extensions[].offerings string[] List of provided products/services desktop
extensions[].dining_options string[] List of dining options desktop
extensions[].atmosphere string[] List of atmosphere descriptions desktop
extensions[].crowd string[] List of customer group descriptions desktop
extensions[].payments string[] List of payment methods desktop
extensions[].children string[] List of child-friendly related descriptions desktop
extensions[].parking string[] List of parking-related options desktop
unsupported_extensions object[] Collection of unsupported extended information desktop
unsupported_extensions[].service_options string[] List of unsupported service options desktop
unsupported_extensions[].dining_options string[] List of unsupported dining options desktop
unsupported_extensions[].planning string[] List of planning-related descriptions desktop
service_options object Key-value description of service options desktop
service_options.Delivery boolean Whether delivery service is supported desktop
service_options.Drive-through boolean Whether drive-through is supported desktop
order_online string Link for online ordering desktop
user_review string User review content desktop