Geocoding API
Introduction
This 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 also returns a complete postal address string and address details.
Request Parameters
Loading..Response Schema
Loading..Examples
Let’s look for the term “market” with a countryCode of USA.
Sample API Request
1curl --location 'https://api.nextbillion.io/geocode?in=countryCode:USA&key=<your_api_key>&at=40.720685,-74.044772&q=market'
Sample API Response
1{2"items": [3{4"title": "New Market, MD, United States",5"id": "vaZCqlvidC1a_t19m45pXg",6"address": {7"label": "New Market, MD, United States",8"countryCode": "USA",9"countryName": "United States",10"stateCode": "MD",11"state": "Maryland",12"county": "Frederick",13"city": "New Market"14},15"scoring": {16"queryScore": 0.33,17"fieldScore": {18"city": 119}20},21"position": {22"lat": 39.38301,23"lng": -77.2696824},25"access": [26{27"lat": 39.38301,28"lng": -77.2696829}30],31"distance": 312170,32"mapView": {33"west": -77.3438,34"south": 39.37098,35"east": -77.21166,36"north": 39.4430137}38},39{40"title": "New Market, AL, United States",41"id": "x03GFeSXJ50d1SC-q6x1LQ",42"address": {43"label": "New Market, AL, United States",44"countryCode": "USA",45"countryName": "United States",46"stateCode": "AL",47"state": "Alabama",48"county": "Madison",49"city": "New Market"50},51"scoring": {52"queryScore": 0.33,53"fieldScore": {54"city": 155}56},57"position": {58"lat": 34.91386,59"lng": -86.4160},61"access": [62{63"lat": 34.91386,64"lng": -86.4165}66],67"distance": 1261791,68"mapView": {69"west": -86.55311,70"south": 34.79852,71"east": -86.25577,72"north": 34.9917573}74},75{76"title": "New Market, TN, United States",77"id": "CzY4gTPbBmhbRkaq8BQlzQ",78"address": {79"label": "New Market, TN, United States",80"countryCode": "USA",81"countryName": "United States",82"stateCode": "TN",83"state": "Tennessee",84"county": "Jefferson",85"city": "New Market"86},87"scoring": {88"queryScore": 0.33,89"fieldScore": {90"city": 191}92},93"position": {94"lat": 36.10017,95"lng": -83.5520596},97"access": [98{99"lat": 36.10017,100"lng": -83.55205101}102],103"distance": 973901,104"mapView": {105"west": -83.64015,106"south": 35.98819,107"east": -83.48022,108"north": 36.19184109}110},111{112"title": "New Market, NC, United States",113"id": "1N-vDvPmTyTCjTQNGRZrXQ",114"address": {115"label": "New Market, NC, United States",116"countryCode": "USA",117"countryName": "United States",118"stateCode": "NC",119"state": "North Carolina",120"county": "Randolph",121"city": "New Market"122},123"scoring": {124"queryScore": 0.33,125"fieldScore": {126"city": 1127}128},129"position": {130"lat": 35.83275,131"lng": -79.86305132},133"access": [134{135"lat": 35.83275,136"lng": -79.86305137}138],139"distance": 743518,140"mapView": {141"west": -79.92535,142"south": 35.81112,143"east": -79.82425,144"north": 35.91557145}146},147{148"title": "New Market, VA, United States",149"id": "QzgS2Pc9oJoOwAmsiT6b-A",150"address": {151"label": "New Market, VA, United States",152"countryCode": "USA",153"countryName": "United States",154"stateCode": "VA",155"state": "Virginia",156"county": "Shenandoah",157"city": "New Market"158},159"scoring": {160"queryScore": 0.33,161"fieldScore": {162"city": 1163}164},165"position": {166"lat": 38.64791,167"lng": -78.67173168},169"access": [170{171"lat": 38.64791,172"lng": -78.67173173}174],175"distance": 458044,176"mapView": {177"west": -78.77675,178"south": 38.60465,179"east": -78.5506,180"north": 38.73969181}182}183]184}185
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 [email protected] for an explanation. |