Searching for places

Basic example

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 Web API Authentication.

cURL

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"
    }
}'

Python

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())

Node.js

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);
  });

Go

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))
}

Structured Data Example

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": "[phone]",
          "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"
  }
}

Request options

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	String | LCID standard locale used for the URL request. Alternatively, user can use auto for automatic locale based on country targeting.
parse	Optional (default = true)	Enum: true | false	Instructs Nimble whether to structure the results into a JSON format or return the raw HTML.

Response

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"
    }
}

Supported parsing fields

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.

Using reviews, place, and next_page links.

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 the next_page link. This triggers an additional Maps API request that fetches the next set of 20 search results, and will include an additional next_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
}

Response Codes

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.