Geocode Postcode API
Introduction
Geocode Postcode API is a geolocation tool that provides users with a simple way to retrieve the geographical coordinates and boundaries of a postal code or ZIP code. Additionally, users can provide location coordinates to get the postal code it belongs to.
The API has a range of potential use cases across multiple domains. In the e-commerce industry, it can be utilized to enhance the accuracy of shipping and delivery processes. Similarly, in the logistics and delivery sector, the API can assist with optimizing routes, resulting in faster deliveries. Online mapping services and location-based apps can leverage the API to recommend nearby businesses and attractions based on a user's geographical location. These are just a few examples of the practical applications of the API that can enhance user experiences in various domains.
Parameters
Loading...Request Body
Loading...Note:
-
The user can include only the
atparameter in the API request to obtain information about the postal code a specific geographic coordinate belongs to.
For example:
1{ 2"at":{"lat": 28.661332, "lng":77.197106}, 3} -
To retrieve information about a specific postal code, include both the
postalcodeand thecountryparameter in the request.
For example:
1 { 2 "postalcode": "110007", 3 "country": "India" 4 } -
We do not recommend using both
postalcodeandattogether in a single request
Response Schema
Loading...Sample Request
1curl --location --request POST 'https://api.nextbillion.io/postalcode?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4"at":{"lat": 34.007578, "lng":-118.271713},
5"country": "USA"
6}'Sample Response
1{
2 "places": [
3 {
4 "geopoint": {
5 "lat": 34.00713949,
6 "lng": -118.2587382
7 },
8 "country": "United States",
9 "countryCode": "USA",
10 "state": "California",
11 "district": "Los Angeles",
12 "postalCode": "90011",
13 "address": "Los Angeles, Los Angeles, California, United States, 90011",
14 "distance": 1197,
15 "boundary": {
16 "multiPolygon": [
17 {
18 "polygon": [
19 {
20 "points": [
21 {
22 "lat": 34.016452,
23 "lng": -118.27402099
24 },
25 {
26 "lat": 34.018654,
27 "lng": -118.27262499
28 },
29 {
30 "lat": 34.018818,
31 "lng": -118.26837099
32 },
33 {
34 "lat": 34.020256,
35 "lng": -118.27160099
36 },
37 {
38 "lat": 34.024847,
39 "lng": -118.26867099
40 },
41 {
42 "lat": 34.027311,
43 "lng": -118.26709899
44 },
45 {
46 "lat": 34.028413,
47 "lng": -118.26491999
48 },
49 {
50 "lat": 34.028952,
51 "lng": -118.26605099
52 },
53 {
54 "lat": 34.030991,
55 "lng": -118.26467899
56 },
57 {
58 "lat": 34.029962,
59 "lng": -118.26244699
60 },
61 {
62 "lat": 34.027467,
63 "lng": -118.26290499
64 },
65 {
66 "lat": 34.027703,
67 "lng": -118.26275699
68 },
69 {
70 "lat": 34.028606,
71 "lng": -118.26218199
72 },
73 {
74 "lat": 34.027571,
75 "lng": -118.25995599
76 },
77 {
78 "lat": 34.026742,
79 "lng": -118.26054299
80 },
81 {
82 "lat": 34.02588,
83 "lng": -118.25855999
84 },
85 {
86 "lat": 34.027631,
87 "lng": -118.25743699
88 },
89 {
90 "lat": 34.026748,
91 "lng": -118.25553399
92 },
93 {
94 "lat": 34.025872,
95 "lng": -118.25611599
96 },
97 {
98 "lat": 34.025845,
99 "lng": -118.25358699
100 },
101 {
102 "lat": 34.023027,
103 "lng": -118.24804199
104 },
105 {
106 "lat": 34.021208,
107 "lng": -118.24659099
108 },
109 {
110 "lat": 34.021421,
111 "lng": -118.245184
112 },
113 {
114 "lat": 34.020172,
115 "lng": -118.24617899
116 },
117 {
118 "lat": 34.019004,
119 "lng": -118.24413799
120 },
121 {
122 "lat": 34.020805,
123 "lng": -118.24399499
124 },
125 {
126 "lat": 34.020595,
127 "lng": -118.24277199
128 },
129 {
130 "lat": 34.018717,
131 "lng": -118.24285599
132 },
133 {
134 "lat": 34.018754,
135 "lng": -118.243023
136 },
137 {
138 "lat": 34.014286,
139 "lng": -118.24323699
140 },
141 {
142 "lat": 34.01385,
143 "lng": -118.24487699
144 },
145 {
146 "lat": 34.013201,
147 "lng": -118.24324699
148 },
149 {
150 "lat": 34.003917,
151 "lng": -118.24337599
152 },
153 {
154 "lat": 33.989443,
155 "lng": -118.24313899
156 },
157 {
158 "lat": 33.989498,
159 "lng": -118.25643599
160 },
161 {
162 "lat": 33.989317,
163 "lng": -118.25643599
164 },
165 {
166 "lat": 33.989227,
167 "lng": -118.26518499
168 },
169 {
170 "lat": 33.989205,
171 "lng": -118.27052799
172 },
173 {
174 "lat": 33.986067,
175 "lng": -118.27052599
176 },
177 {
178 "lat": 33.986143,
179 "lng": -118.27180699
180 },
181 {
182 "lat": 33.9892,
183 "lng": -118.27180799
184 },
185 {
186 "lat": 33.989191,
187 "lng": -118.27392799
188 },
189 {
190 "lat": 33.995227,
191 "lng": -118.27394799
192 },
193 {
194 "lat": 33.996514,
195 "lng": -118.27284399
196 },
197 {
198 "lat": 33.996505,
199 "lng": -118.27395299
200 },
201 {
202 "lat": 34.002014,
203 "lng": -118.27397199
204 },
205 {
206 "lat": 34.003835,
207 "lng": -118.27278999
208 },
209 {
210 "lat": 34.003831,
211 "lng": -118.27342799
212 },
213 {
214 "lat": 34.005683,
215 "lng": -118.27398399
216 },
217 {
218 "lat": 34.013057,
219 "lng": -118.27400899
220 },
221 {
222 "lat": 34.016452,
223 "lng": -118.27402099
224 }
225 ]
226 }
227 ]
228 }
229 ]
230 }
231 }
232 ]
233}API Query Limits
-
Only 1
postalcodeis allowed per request. -
Only 1
atlocation is allowed per request. -
The Geocode Postcode API supports the following countries currently:
- United States of America
- India
- United Kingdom
- Netherlands
- Austria
- Germany
- Indonesia
- France
- Singapore
- Philippines
- Canada
- Australia
- New Zealand
- Italy
-
Nextbillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests. Note: We can increase the quota if needed on request. Contact [email protected] for more details
API Error Codes
| Response Code | Description | Additional Notes |
|---|---|---|
| 200 | Normal success case. | Normal success case. |
| 400 | Input validation failed. | There is a missing or 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. | The request could not be processed due to inappropriate input. Please verify the accuracy of the postal code or the location. |
| 429 | Too many requests. | QPM reached 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. |
