Search Places APIs

Introduction

NextBillion.ai provides two convenient methods to search for unknown places and discover new ones matching the generic queries provided. The Discover API can suggest matching places based on free-form or incomplete queries provided while the Browse API allows for a more structured search based on different filters like place category or a given search center. Both these endpoints help users with searching unknown places based on custom criteria or queries.

Let’s cover both these endpoints one-by-one in the following sections.

Discover API

The Discover API allows processing a free-form text query to look for matching addresses or places and return the results in order of relevance.

Request Parameters

Response Schema

Example

Lets create a basic discover request in San Francisco area

Sample API Request

1
curl --location 'https://api.nextbillion.io/discover?key=<your_api_key>&at=37.78182,-122.45291&q=gas&limit=5&in=countryCode:USA,MEX'

Sample API Response

1
{
2
   "items": [
3
   "{...}",
4
   "{...}",
5
   ]
6
}

Browse API

The Browse API provides search results for places based on different filters, such as categories or name, ranked by distance from a given search center. The only mandatory elements exposed in the response are id, scoring and position. The other elements shown in the response may or may not be returned based on the details available in the dataset.

Request Parameters

Response Schema

Example

Let’s browse for “market” in the San Francisco area.

Sample API Request

1
curl --location 'https://api.nextbillion.io/browse?categories=market&limit=2&in=countryCode:USA,MEX&at=37.78182,-122.45291&key=<your_api_key>'

Sample API Response

1
{
2
   "items": [
3
   "{...}",
4
   "{...}",
5
   ]
6
}

API Query Limits

NextBillion.ai allows a maximum rate limit of 2400 queries per minute or 40 queries/second for continuous requests.

API Error Codes