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

Request options

ParameterRequiredTypeDescription

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.

A successful result includes a number of follow-up links that can be used to get more information or browse through pagination. These include:

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

StatusDescription

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 updated