Autocomplete API

Introduction

NextBillion.ai Autocomplete API completes valid street addresses or administrative areas using the entered keystrokes to speed-up the process of completing the address search queries.

Request Parameters

Response Schema

Examples

Let’s look for places containing stat word in their names in Oklahoma City region

Sample API Request

1
curl --location 'https://api.nextbillion.io/autocomplete?q=stat&at=35.476911,-97.487201&limit=5&in=countryCode:USA, MEX&key=<your_api_key>'

Sample API Response

1
{
2
   "items": [
3
       {
4
           "title": "State Capitol",
5
           "id": "qN08rVNZIciFxFJeg3hgow",
6
           "address": {
7
               "label": "State Capitol, 2300 North Lincoln Boulevard, Oklahoma City, OK 73105, United States",
8
               "countryCode": "USA",
9
               "countryName": "United States",
10
               "stateCode": "OK",
11
               "state": "Oklahoma",
12
               "county": "Oklahoma",
13
               "city": "Oklahoma City",
14
               "street": "North Lincoln Boulevard",
15
               "postalCode": "73105-4805",
16
               "houseNumber": "2300"
17
           },
18
           "scoring": {
19
               "queryScore": 1
20
           },
21
           "position": {
22
               "lat": 35.491815,
23
               "lng": -97.503339
24
           },
25
           "access": [
26
               {
27
                   "lat": 35.49114,
28
                   "lng": -97.50331
29
               },
30
               {
31
                   "lat": 35.49158,
32
                   "lng": -97.50149
33
               }
34
           ],
35
           "distance": 2209,
36
           "mapView": {
37
               "west": -97.50521,
38
               "south": 35.49029,
39
               "east": -97.50147,
40
               "north": 35.49334
41
           },
42
           "categories": [
43
               {
44
                   "id": "7376",
45
                   "name": "important tourist attraction",
46
                   "primary": true
47
               }
48
           ],
49
           "contacts": [
50
               {
51
                   "www": [
52
                       {
53
                           "value": "www.okhouse.gov/Information/CapitolTours.aspx"
54
                       }
55
                   ]
56
               }
57
           ]
58
       },
59
       {
60
           "title": "United States Postal Service",
61
           "id": "wFfRtLgHYeJfAoKawwoNKw",
62
           "address": {
63
               "label": "United States Postal Service, 701 North Kelley Avenue, Oklahoma City, OK 73117, United States",
64
               "countryCode": "USA",
65
               "countryName": "United States",
66
               "stateCode": "OK",
67
               "state": "Oklahoma",
68
               "county": "Oklahoma",
69
               "city": "Oklahoma City",
70
               "street": "North Kelley Avenue",
71
               "postalCode": "73117-1400",
72
               "houseNumber": "701"
73
           },
74
           "scoring": {
75
               "queryScore": 0.99
76
           },
77
           "position": {
78
               "lat": 35.473932,
79
               "lng": -97.495284
80
           },
81
           "access": [
82
               {
83
                   "lat": 35.47393,
84
                   "lng": -97.49517
85
               }
86
           ],
87
           "distance": 803,
88
           "mapView": {
89
               "west": -97.49639,
90
               "south": 35.47303,
91
               "east": -97.49418,
92
               "north": 35.47483
93
           },
94
           "categories": [
95
               {
96
                   "id": "7324003",
97
                   "name": "post office, local",
98
                   "primary": true
99
               }
100
           ],
101
           "contacts": [
102
               {
103
                   "phone": [
104
                       {
105
                           "value": "+1 405-236-0534"
106
                       }
107
                   ],
108
                   "www": [
109
                       {
110
                           "value": "www.usps.com"
111
                       }
112
                   ]
113
               }
114
           ]
115
       },
116
       {
117
           "title": "Staton Drive, Oklahoma City, OK 73111, United States",
118
           "id": "hDHq2NbnFEtoP5otpkeQIA",
119
           "address": {
120
               "label": "Staton Drive, Oklahoma City, OK 73111, United States",
121
               "countryCode": "USA",
122
               "countryName": "United States",
123
               "stateCode": "OK",
124
               "state": "Oklahoma",
125
               "county": "Oklahoma",
126
               "city": "Oklahoma City",
127
               "street": "Staton Drive",
128
               "postalCode": "73111"
129
           },
130
           "scoring": {
131
               "queryScore": 0.99
132
           },
133
           "position": {
134
               "lat": 35.510759,
135
               "lng": -97.489053
136
           },
137
           "access": [
138
               {
139
                   "lat": 35.510759,
140
                   "lng": -97.489053
141
               }
142
           ],
143
           "distance": 3767,
144
           "mapView": {
145
               "west": -97.48995,
146
               "south": 35.50959,
147
               "east": -97.48813,
148
               "north": 35.51154
149
           }
150
       },
151
       {
152
           "title": "Jeremy Henley - State Farm",
153
           "id": "U1yvkrTAXTeIhgXRPkagVQ",
154
           "address": {
155
               "label": "Jeremy Henley - State Farm, 114 Northwest 6th Street, Oklahoma City, OK 73102, United States",
156
               "countryCode": "USA",
157
               "countryName": "United States",
158
               "stateCode": "OK",
159
               "state": "Oklahoma",
160
               "county": "Oklahoma",
161
               "city": "Oklahoma City",
162
               "street": "Northwest 6th Street",
163
               "postalCode": "73102-6015",
164
               "houseNumber": "114"
165
           },
166
           "scoring": {
167
               "queryScore": 0.96
168
           },
169
           "position": {
170
               "lat": 35.473743,
171
               "lng": -97.515228
172
           },
173
           "access": [
174
               {
175
                   "lat": 35.47399,
176
                   "lng": -97.51512
177
               },
178
               {
179
                   "lat": 35.47399,
180
                   "lng": -97.51512
181
               }
182
           ],
183
           "distance": 2562,
184
           "mapView": {
185
               "west": -97.51633,
186
               "south": 35.47284,
187
               "east": -97.51412,
188
               "north": 35.47464
189
           },
190
           "categories": [
191
               {
192
                   "id": "9352007",
193
                   "name": "insurance, company",
194
                   "primary": true
195
               }
196
           ],
197
           "contacts": [
198
               {
199
                   "phone": [
200
                       {
201
                           "value": "+1 405-605-4466"
202
                       }
203
                   ],
204
                   "www": [
205
                       {
206
                           "value": "www.jeremyhenley.com"
207
                       }
208
                   ]
209
               }
210
           ]
211
       },
212
       {
213
           "title": "Statesboro, GA, United States",
214
           "id": "a60FRgx3mffb2MWJWEcFUg",
215
           "address": {
216
               "label": "Statesboro, GA, United States",
217
               "countryCode": "USA",
218
               "countryName": "United States",
219
               "stateCode": "GA",
220
               "state": "Georgia",
221
               "county": "Bulloch",
222
               "city": "Statesboro"
223
           },
224
           "scoring": {
225
               "queryScore": 0.95
226
           },
227
           "position": {
228
               "lat": 32.44877,
229
               "lng": -81.777753
230
           },
231
           "access": [
232
               {
233
                   "lat": 32.44877,
234
                   "lng": -81.777753
235
               }
236
           ],
237
           "distance": 1485645,
238
           "mapView": {
239
               "west": -81.97639,
240
               "south": 32.26011,
241
               "east": -81.52527,
242
               "north": 32.65335
243
           }
244
       }
245
   ]
246
}
247

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.