# Forward Geocode API ## Introduction NextBillion.ai Forward Geocode API allows you to find the geo-coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It returns the complete postal address of the searched place along with relevant details. ## Request Parameters | Name | Required | Format and Usage | Description | |------|----------|------------------|-------------| | `key` | Yes | Type: `string`
Format: 32 character alphanumeric string
Example: `key=API_KEY` | A key is a unique identifier that is required to authenticate a request to the API. | | `q` | Yes | Type: `string`
Example: `q=125, Berliner, berlin`, `q=Beacon, Boston, Hospital` | Specify the free-text search query.
Please note that whitespace, urls, email addresses, or other out-of-scope queries will yield no results. | | `at` | No | Type: `string`
Format: latitude,longitude
Example: `at=52.5308,13.3856` | Specify the center of the search context expressed as coordinates.
Please note that one of "at", "in=circle" or "in=bbox" should be provided for relevant results. | | `in` | No | Type: `string`
Example: `in=countryCode:CAN,MEX,USA`, `in=circle:52.53,13.38;r=10000`, `in=bbox:13.08836,52.33812,13.761,52.6755` | Search within a geographic area. This is a hard filter. Results will be returned if they are located within the specified area.
A geographic area can be
\* a country (or multiple countries), provided as comma-separated [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-3) country codes
The country codes are to be provided in all uppercase.
Format: `countryCode:{countryCode}[,{countryCode}]`
\* a circular area, provided as latitude, longitude, and radius (an integer with meters as unit)
Format: `circle:{latitude},{longitude};r={radius}`
\* a bounding box, provided as \_west longitude\_, \_south latitude\_, \_east longitude\_, \_north latitude\_
Format: `bbox:{west longitude},{south latitude},{east longitude},{north latitude}`
Please provide one of 'at', 'in=circle' or 'in=bbox' input for a relevant result. | | `types` | No | Type: `string`

Allowed values: `houseNumber`, `addressBlock`, `street`, `intersection`, `place`, `area`
Example: `types=houseNumber,addressBlock` | Restricts results to the specified types. If omitted, results are not restricted by type. Please note that:
\* Allowed Values:
- `houseNumber`: Exact door point
- `addressBlock`: Address-range/segment match, including interpolated house numbers
- `street`: Street level only
- `intersection`: Cross street intersections
- `place`: Point of Interest
- `area`: A city\/district\/postal\/admin area
\* For range based addresses, such as "600-699 Golden Gate Ave", use `types=addressBlock` to retrieve address-range or segment matches. Exact door-point addresses are excluded from range interpolation, so `types=addressBlock` with an exact single-address query can match same-numbered ranges in other cities.
\* `intersection` results are returned only when explicitly requested.
\* If invalid values are specified then the service returns an error. | | `limit` | No | Type: `integer`
Default: `10` | Maximum number of results to be returned. | | `lang` | No | Type: `string`
Example: `lang=en-US` | Select the language to be used for result rendering from a list of [IETF Supported Language Tags](https://developer.tomtom.com/geocoding-api/documentation/product-information/supported-languages) [](https://developer.tomtom.com/geocoding-api/documentation/product-information/supported-languages)compliant language codes. | | `view` | No | Type: `string` | Select the geopolitical view to be applied to the result to handle disputed territories. Following are the allowed values:
\* `Unified` - neutral, global representation
\* `AR` - Argentina
\* `IL` - Israel
\* `IN` - India
\* `MA` - Morocco
\* `PK` - Pakistan
\* `RU` - Russia
\* `TR` - Turkey
\* `CN` - China
\* `TW` - Taiwan
Please note that:
\* For requests originating from one of the supported regions, the default view is the region itself.
Example: Requests from Argentina default to `AR`, from China to `CN`, and so on.
\* For requests originating from all other regions, the default view is `Unified`.
For India (`IN`), no alternate geopolitical views are supported. | ## Response Schema | Field | Type | Description | |-------|------|-------------| | `items` | array of object | The results are presented as a JSON list of candidates in ranked order (most-likely to least-likely) based on the matched location criteria. | | `items[].title` | string | The localized display name of this result item. | | `items[].id` | string | The unique identifier for the result item. | | `items[].type` | string | Returns the geographical category that this result belongs to, hence implying the granularity of the match. When the result classification is available, it will always be one of `houseNumber` (exact door-point address), `addressBlock` (address-range or segment match, including single numbers resolved by range interpolation), `street` (street-level only), `intersection` (cross-street), `place` (POI), `area` (locality, administrative area, or postal area). If the classification is not available then this field is not returned.| | `items[].address` | object | Returns the details of the postal address of the searched place. | | `items[].address.label` | string | Assembled address value built out of the individual address components according to the regional postal rules. It may not include all the input terms. | | `items[].address.countryCode` | string | The alpha-3 country code as per [ISO 3166-1](https://en.wikipedia.org/wiki/ISO\_3166-1) standard. | | `items[].address.countryName` | string | The localised country name. | | `items[].address.stateCode` | string | The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO\_3166-2) compliant state code. For example, "CA" for California as per ISO 3166-2 standard for states in USA. | | `items[].address.state` | string | Name of the state or primary division of the country. | | `items[].address.county` | string | A division of a state; typically, a primary-level administrative division of a state or equivalent. | | `items[].address.city` | string | The name of the primary locality of the searched place. | | `items[].address.neighborhood` | string | A division of city or a neighborhood within the city. | | `items[].address.street` | string | Name of street of the searched place, if available. | | `items[].address.postalCode` | string | The zip or postal code of the searched place. | | `items[].address.houseNumber` | string | House number of the searched place, if available. | | `items[].scoring` | object | Query matching score of the searched place. A higher score indicates a closer match with the searched query. | | `items[].scoring.queryScore` | number | A score, out of 1, indicating how closely the result matches with the provided query `q` . | | `items[].scoring.fieldScore` | object | A breakdown of how closely individual field of the result matched with the provided query `q`. | | `items[].position` | object | Returns the location coordinates of the searched place. | | `items[].position.lat` | number | The latitude of the searched place. | | `items[].position.lng` | number | The longitude of the searched place. | | `items[].access` | array of object | An array returning the location coordinates of all the access points of the search result. | | `items[].access[].lat` | number | The latitude of the access point of the search result. | | `items[].access[].lng` | number | The longitude of the access point of the search result. | | `items[].distance` | integer | The distance "as the crow flies" from the search center to this result item in meters. | | `items[].mapView` | object | The bounding box enclosing the geometric shape (area or line) that an individual searched place covers. `place` type results have no `mapView`. | | `items[].mapView.west` | number | Longitude of the western-side of the box. | | `items[].mapView.south` | number | Longitude of the southern-side of the box. | | `items[].mapView.east` | number | Longitude of the eastern-side of the box. | | `items[].mapView.north` | number | Longitude of the northern-side of the box. | | `items[].addressRanges` | object | Address-range details returned only for `addressBlock` results when available. For a block-range query, `position` is one end of the segment; the midpoint of `addressRanges.from` and `addressRanges.to` best represents the whole block. | | `items[].addressRanges.rangeLeft` | string | House-number range on the left side of the street (assuming looking from the “from” end toward the “to” end), returned when available. | | `items[].addressRanges.rangeRight` | string | House-number range on the right side of the street (assuming looking from the “from” end toward the “to” end), returned when available. | | `items[].addressRanges.from` | object | Start point of the covered street segment. | | `items[].addressRanges.from.lat` | number | Latitude for the start point of covered street segment. | | `items[].addressRanges.from.lng` | number | Longitude for the start point of covered street segment. | | `items[].addressRanges.to` | object | End point of the covered street segment. | | `items[].addressRanges.to.lat` | number | Latitude for the end point of covered street segment. | | `items[].addressRanges.to.lng` | number | Longitude for the end point of covered street segment. | | `items[].categories` | array of object | The list of categories assigned to this place. | | `items[].categories[].id` | string | Identifier number for the place category associated with the searched place. | | `items[].categories[].name` | string | Name of the place category for the searched place. | | `items[].categories[].primary` | boolean | Whether or not it is a primary category. This field is visible only when the value is 'true'. | | `items[].contacts` | array of object | Contact information like phone, email or website. | | `items[].contacts[].phone` | array of object | | | `items[].contacts[].phone[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].phone[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].phone[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].phone[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].contacts[].mobile` | array of object | | | `items[].contacts[].mobile[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].mobile[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].mobile[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].mobile[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].contacts[].tollFree` | array of object | | | `items[].contacts[].tollFree[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].tollFree[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].tollFree[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].tollFree[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].contacts[].fax` | array of object | | | `items[].contacts[].fax[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].fax[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].fax[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].fax[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].contacts[].www` | array of object | | | `items[].contacts[].www[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].www[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].www[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].www[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].contacts[].email` | array of object | | | `items[].contacts[].email[].label` | string | Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax". | | `items[].contacts[].email[].value` | string | Contact information, as specified by the contact type. | | `items[].contacts[].email[].categories` | array of object | The list of place categories this contact refers to. | | `items[].contacts[].email[].categories[].id` | string | Identifier number for an associated category. For example: "900-9300-0000" | | `items[].openingHours` | object | Returns the operating hours of the place, if available. | | `items[].openingHours.timeRanges` | array of object | A collection of attributes with details about the opening and closing hours for each day of the week. | | `items[].openingHours.timeRanges[].startTime` | object | Returns the open time details. | | `items[].openingHours.timeRanges[].startTime.date` | string | The date to which the subsequent open time details belong to. | | `items[].openingHours.timeRanges[].startTime.hour` | integer | The hour of the day when the place opens. | | `items[].openingHours.timeRanges[].startTime.minute` | integer | The minute of the hour when the place opens. | | `items[].openingHours.timeRanges[].endTime` | object | Returns the closing time details. | | `items[].openingHours.timeRanges[].endTime.date` | string | The date to which the subsequent closing time details belong to. | | `items[].openingHours.timeRanges[].endTime.hour` | integer | The hour of the day when the place closes. | | `items[].openingHours.timeRanges[].endTime.minute` | integer | The minute of the hour when the place closes. | ## Examples Let’s look for the term “market” with a countryCode of USA. ### Sample API Request ```bash curl --location 'https://api.nextbillion.io/geocode?in=countryCode:USA&key=&at=40.720685,-74.044772&q=market' ``` ### Sample API Response ```json { "items": [ { "title": "New Market, MD, United States", "id": "vaZCqlvidC1a_t19m45pXg", "address": { "label": "New Market, MD, United States", "countryCode": "USA", "countryName": "United States", "stateCode": "MD", "state": "Maryland", "county": "Frederick", "city": "New Market" }, "scoring": { "queryScore": 0.33, "fieldScore": { "city": 1 } }, "position": { "lat": 39.38301, "lng": -77.26968 }, "access": [ { "lat": 39.38301, "lng": -77.26968 } ], "distance": 312170, "mapView": { "west": -77.3438, "south": 39.37098, "east": -77.21166, "north": 39.44301 } }, { "title": "New Market, AL, United States", "id": "x03GFeSXJ50d1SC-q6x1LQ", "address": { "label": "New Market, AL, United States", "countryCode": "USA", "countryName": "United States", "stateCode": "AL", "state": "Alabama", "county": "Madison", "city": "New Market" }, "scoring": { "queryScore": 0.33, "fieldScore": { "city": 1 } }, "position": { "lat": 34.91386, "lng": -86.41 }, "access": [ { "lat": 34.91386, "lng": -86.41 } ], "distance": 1261791, "mapView": { "west": -86.55311, "south": 34.79852, "east": -86.25577, "north": 34.99175 } }, { "title": "New Market, TN, United States", "id": "CzY4gTPbBmhbRkaq8BQlzQ", "address": { "label": "New Market, TN, United States", "countryCode": "USA", "countryName": "United States", "stateCode": "TN", "state": "Tennessee", "county": "Jefferson", "city": "New Market" }, "scoring": { "queryScore": 0.33, "fieldScore": { "city": 1 } }, "position": { "lat": 36.10017, "lng": -83.55205 }, "access": [ { "lat": 36.10017, "lng": -83.55205 } ], "distance": 973901, "mapView": { "west": -83.64015, "south": 35.98819, "east": -83.48022, "north": 36.19184 } }, { "title": "New Market, NC, United States", "id": "1N-vDvPmTyTCjTQNGRZrXQ", "address": { "label": "New Market, NC, United States", "countryCode": "USA", "countryName": "United States", "stateCode": "NC", "state": "North Carolina", "county": "Randolph", "city": "New Market" }, "scoring": { "queryScore": 0.33, "fieldScore": { "city": 1 } }, "position": { "lat": 35.83275, "lng": -79.86305 }, "access": [ { "lat": 35.83275, "lng": -79.86305 } ], "distance": 743518, "mapView": { "west": -79.92535, "south": 35.81112, "east": -79.82425, "north": 35.91557 } }, { "title": "New Market, VA, United States", "id": "QzgS2Pc9oJoOwAmsiT6b-A", "address": { "label": "New Market, VA, United States", "countryCode": "USA", "countryName": "United States", "stateCode": "VA", "state": "Virginia", "county": "Shenandoah", "city": "New Market" }, "scoring": { "queryScore": 0.33, "fieldScore": { "city": 1 } }, "position": { "lat": 38.64791, "lng": -78.67173 }, "access": [ { "lat": 38.64791, "lng": -78.67173 } ], "distance": 458044, "mapView": { "west": -78.77675, "south": 38.60465, "east": -78.5506, "north": 38.73969 } } ] } ``` ## 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 | Response Code | Description | Additional Notes | | --- | --- | --- | | 200 | Normal success case. | Normal success case | | 400 | Input validation failed. | There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request. | | 401 | APIKEY not supplied or invalid. | This error occurs when the wrong API key is passed in the request or the key is missing altogether | | 403 | APIKEY is valid but does not have access to requested resources. | You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you. | | 404 | Requested host/path not found. | This error occurs when a malformed hostname is used. | | 422 | Could not process the request. | Valid results could not be generated for the given parameters. Please modify the constraints/search query. | | 429 | Too many requests. | QPM or API request count quota reached | | 500 | Internal Service error. | There was an internal issue with NextBillion.ai services. You can reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) for an explanation. |