Comment on page
Searching for places
To search for places around a set of geographic coordinates, use the /realtime/serp endpoint and set
search_engine
to google_maps_search
, as in the example below:Nimble APIs requires that a base64 encoded credential string be sent with every request to authenticate your account. For detailed examples, see Maps API Authentication.
cURL
Python
Node.js
Go
curl --location --request POST 'https://api.webit.live/api/v1/realtime/serp' \
--header 'Authorization: Basic <credential string>' \
--header 'Content-Type: application/json' \
--data-raw '{
"search_engine": "google_maps_search",
"query": "Cinema",
"coordinates": {
"latitude": "40.7123695",
"longitude": "-74.0357317"
}
}'
import requests
url = 'https://api.webit.live/api/v1/realtime/serp'
headers = {
'Authorization': 'Basic <credential string>',
'Content-Type': 'application/json'
}
data = {
"search_engine": "google_maps_search",
"query": "Cinema",
"coordinates": {
"latitude": "40.7123695",
"longitude": "-74.0357317"
}
}
response = requests.post(url, headers=headers, json=data)
print(response.status_code)
print(response.json())
const axios = require('axios');
const url = 'https://api.webit.live/api/v1/realtime/serp';
const headers = {
'Authorization': 'Basic <credential string>',
'Content-Type': 'application/json'
};
const data = {
"search_engine": "google_maps_search",
"query": "Cinema",
"coordinates": {
"latitude": "40.7123695",
"longitude": "-74.0357317"
}
};
axios.post(url, data, { headers })
.then(response => {
console.log(response.status);
console.log(response.data);
})
.catch(error => {
console.error(error);
});
package main
import (
"bytes"
"fmt"
"net/http"
"encoding/json"
)
func main() {
url := "https://api.webit.live/api/v1/realtime/serp"
payload := []byte(`{
"search_engine": "google_maps_search",
"query": "Cinema",
"coordinates": {
"latitude": "40.7123695",
"longitude": "-74.0357317"
}
}`)
headers := map[string]string{
"Authorization": "Basic <credential string>",
"Content-Type": "application/json",
}
req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload))
if err != nil {
fmt.Println(err)
return
}
for key, value := range headers {
req.Header.Set(key, value)
}
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
// Read the response body if needed
// body, err := ioutil.ReadAll(resp.Body)
// fmt.Println(string(body))
}
Nimble's Maps API uses AI to intelligently structure the rich information available through maps engines. For example, the above request returns the following data:
{
"status": "success",
"query_time": ...,
"html_content": ...,
"status_code": 200,
"headers": {
...
},
"parsing": {
"status": "success",
"entities": {
"SearchResult": [
{
"accessibility": [
{
"description": "Has wheelchair accessible entrance",
"display_name": "Wheelchair accessible entrance",
"full_path_name": "/geo/type/establishment_poi/has_wheelchair_accessible_entrance",
"is_available": true
},
{
"description": "No wheelchair accessible parking lot",
"display_name": "Wheelchair accessible parking lot",
"full_path_name": "/geo/type/establishment_poi/has_wheelchair_accessible_parking",
"is_available": false
}
],
"address": "22 E 12th St, New York, NY 10003",
"amenities": [
{
"description": "Has restroom",
"display_name": "Restroom",
"full_path_name": "/geo/type/establishment_poi/has_restroom",
"is_available": true
},
{
"description": "No restaurant",
"display_name": "Restaurant",
"full_path_name": "/geo/type/establishment_poi/has_restaurant",
"is_available": false
}
],
"business_category": [
"Movie theater"
],
"business_description": [
"Indie-film arthouse",
"Longtime West Village theater known for showing offbeat & foreign movies, plus documentaries."
],
"cid": "13653966557094385217",
"city": "New York",
"country": "US",
"csrf_token": "LxdSZYbCIcWGptQPt5KHqAI",
"data_id": "0x89c25999ca135ddd:0xbd7ca23deaac9641",
"entity_type": "SearchResult",
"highlights": [
{
"description": "Has live performances",
"display_name": "Live performances",
"full_path_name": "/geo/type/establishment_poi/has_live_performances",
"is_available": true
}
],
"latitude": "40.7340823",
"longitude": "-73.9933681",
"number_of_reviews": "399",
"offerings": [
{
"description": "Serves food",
"display_name": "Food",
"full_path_name": "/geo/type/establishment_poi/serves_food",
"is_available": true
}
],
"page_index": 0,
"payments": [
{
"description": "Accepts credit cards",
"display_name": "Credit cards",
"full_path_name": "/geo/type/establishment_poi/pay_credit_card",
"is_available": true
},
{
"description": "Accepts debit cards",
"display_name": "Debit cards",
"full_path_name": "/geo/type/establishment_poi/pay_debit_card",
"is_available": true
},
{
"description": "Accepts NFC mobile payments",
"display_name": "NFC mobile payments",
"full_path_name": "/geo/type/establishment_poi/pay_mobile_nfc",
"is_available": true
}
],
"phone_number": "(212) 924-3364",
"place_id": "ChIJ3V0TyplZwokRQZas6j2ifL0",
"place_information": {
"photos": [
{
"image_url": "https://lh5.googleusercontent.com/p/AF1QipPcB_h4ltcIsjDvReMUmep7pxEdIdmU_KoSDtB-=w114-h86-k-no",
"latitude": "40.7341443",
"longitude": "-73.9933229",
"max_height": 3024,
"max_width": 4032,
"position": 0,
"source_type": "photos:gmm_android"
},
{
"image_url": "https://lh5.googleusercontent.com/p/AF1QipPcB_h4ltcIsjDvReMUmep7pxEdIdmU_KoSDtB-=w408-h306-k-no",
"latitude": "40.7341443",
"longitude": "-73.9933229",
"max_height": 3024,
"max_width": 4032,
"position": 1,
"source_type": "photos:gmm_android"
}
],
"reviews_link": "https://search.google.com/local/reviews?placeid=ChIJ3V0TyplZwokRQZas6j2ifL0&q=Cinema&authuser=0&hl=en&gl=US",
"website_url": "https://www.cinemavillage.com/"
},
"place_url": "https://www.google.com/maps/search/?api=1&query=40.7340823%2C-73.9933681&query_place_id=ChIJ3V0TyplZwokRQZas6j2ifL0",
"position": 1,
"rating": "4.3 stars",
"review_summary": {
"overall_rating": 4.3,
"ratings_count": {
"1": 11,
"2": 11,
"3": 39,
"4": 107,
"5": 231
},
"review_count": 399
},
"sponsored": false,
"street_address": "22 E 12th St",
"title": "Cinema Village",
"zip_code": "10003",
"nimble_reviews_link": "https://api.webit.live/api/v1/realtime/serp?parse=true&search_engine=google_maps_reviews&domain=com&format=json&render=false&country=ALL&locale=en&csrf_token=LxdSZYbCIcWGptQPt5KHqAI&place_id=ChIJ3V0TyplZwokRQZas6j2ifL0",
"nimble_place_link": "https://api.webit.live/api/v1/realtime/serp?parse=true&search_engine=google_maps_place&domain=com&format=json&render=false&country=ALL&locale=en&place_id=ChIJ3V0TyplZwokRQZas6j2ifL0"
},
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... },
{ ... }
],
"SearchResultMetaData": [
{
"entity_type": "SearchResultMetaData",
"latitude": "40.71236584",
"longitude": "-74.03573171",
"zoom": "13"
}
]
},
"total_entities_count": 21,
"entities_count": {
"SearchResult": 20,
"SearchResultMetaData": 1
},
"metrics": {}
},
"url": "https://www.google.com/maps/search/Cinema/@40.7123695,-74.0357317,14z?hl=en&ie=UTF-8&sourceid=chrome&oq=Cinema",
"nimble_links": {
"next_page": "https://api.webit.live/api/v1/realtime/serp?parse=true&search_engine=google_maps_search&query=Cinema&domain=com&coordinates=%4040.7123695%2C-74.0357317%2C14z&format=json&render=false&country=ALL&locale=en&offset=20"
}
}
Parameter | Required | Type | Description |
---|---|---|---|
query | Required | String | The term or phrase to search for. |
search_engine | Required | Enum: google_maps_search | google_maps_place | google_maps_reviews | The search engine from which to collect results. |
coordinates | Optional | String or Object
"@{latitude},{longitude},{zoom}z" | The coordinates to target. When using a string, zoom is required.
|
| | "coordinates": { "latitude": "40.7590562", "longitude": "-74.0042502",
"zoom": "14" } | When using an object, zoom is optional. |
offset | Optional | Integer | Offset the pagination position by this number of listings (eg: 20). |
domain | Optional | String | Search through a custom top-level domain of Google. eg: "co.uk" |
country | Optional (default = all) | String | Country used to access the target URL, use ISO Alpha-2 Country Codes i.e. US, DE, GB |
locale | Optional (default = en) | String | LCID standard locale used for the URL request. |
parse | Optional (default = true) | Enum: true | false | Instructs Nimble whether to structure the results into a JSON format or return the raw HTML. |
200 - OK
If the request is executed successfully and parsing is either omitted or set to true, the output will resemble the example below:
{
"status": "success",
"html_content": "...",
"status_code": 200,
"headers": {
...
},
"parsing": {
"status": "success",
"entities": {
"SearchResult": [
{
...
"nimble_reviews_link": "https://api.webit.live/api/v1/realtime/serp?search_engine=google_maps_reviews&csrf_token=cjHpY_DuJqSr5NoP8P6wuAo&place_id=ChIJ_58pLKJZwokRvRwO5eftKC8",
"nimble_place_link": "https://api.webit.live/api/v1/realtime/serp?search_engine=google_maps_place&place_id=ChIJ_58pLKJZwokRvRwO5eftKC8"
},
{...}
]
},
"total_entities_count": 20,
"entities_count": {
"SearchResult": 20
},
"metrics": {}
},
"url": "https://www.google.com/maps/search/Cinema/@40.7123695,-74.0357317,14z",
"nimble_links": {
"next_page": "https://api.webit.live/api/v1/realtime/serp?search_engine=google_maps_search&query=Cinema&coordinates=%4040.7123695%2C-74.0357317%2C14z&offset=20"
}
}
Below is a list of all the fields supported by Nimble's parsing engine. This list is always growing and subject to change. Additionally, while Nimble supports all of these fields, which fields are available depends on the external search engine as well, and thus different fields will be available at different times.
PlusCode
PageIndex
Position
Title
Address
StreetAddress
ZipCode
City
Country
Floor
Sponsored
PlaceId
DataId
PlaceUrl
BusinessCategory
BusinessDescription
Rating
NumberOfReviews
PhoneNumber
Services*
Accessibility*
Offerings*
Planning*
Recycling*
Payments*
Highlights*
PopularFor*
DiningOptions*
Amenities*
Atmosphere*
Crowd*
PriceLevel
PlaceInformation
Longitude
Latitude
TopReviews
ReviewSummary
CsrfToken
DataIdLatitude
DataIdLongitude
LocatedIn
BusinessStatus
LastConfirmedStatus
*marked fields vary according to the available data, and vary according to the creator of the Place.
A successful result includes a number of follow-up links that can be used to get more information or browse through pagination. These include:
nimble_reviews_link
- this link will trigger an additional Maps API request that returns the reviews for a particular place. Each place returned by the search will have its own reviews link. For more information, see the Collecting reviews page.nimble_place_link
- this link will trigger an additional Maps API request that returns additional data for a particular place. Each place returned by the search will have its own reviews link. For more information, see the Getting information about a place page.next_page
- Due to pagination, search results are displayed in groups of 20. If more than 20 results are found, the next set can be accessed using thenext_page
link. This triggers an additional Maps API request that fetches the next set of 20 search results, and will include an additionalnext_page
link if there are surplus search results, and so on.
500 Error
{
"status": "error",
"task_id": "<task_id>",
"msg": "can't download the query response - please try again"
}
400 Input Error
{
"status": "failed",
"msg": error
}
Status | Description |
---|---|
200 | OK. |
400 | The requested resource could not be reached. |
401 | Unauthorized/invalid credental string. |
500 | Internal service error. |
501 | An error was encountered by the proxy service. |
Last modified 18d ago