My Geocode

Guides

Reverse geocode a list of coordinates without writing a loop

· 3 min read · My Geocode · #reverse-geocoding#batch#bulk#coordinates

If you have a table of latitude and longitude pairs and a script that calls the API once per row, you are paying for the round trips, not for the lookups themselves. The reverse geocoding endpoint takes a bulk POST body the same way the forward endpoint does, resolving every pair in one call.

Sending coordinate pairs

Instead of one GET request per point, send an array of coordinate objects to /v1/reverse. Each item returns its own address, in the order it was submitted.

POST /v1/reverse
Content-Type: application/json

[{"lat": 48.8584, "lon": 2.2945}, {"lat": 40.6892, "lon": -74.0445}]
{
  "status": "ok",
  "results": [
    {"formatted": "Champ de Mars, Paris, France", "lat": 48.8584, "lon": 2.2945, "type": "address", "precision": "street", "confidence": 0.9, "place_id": "gh789", "components": {}},
    {"formatted": "Liberty Island, New York, NY", "lat": 40.6892, "lon": -74.0445, "type": "address", "precision": "street", "confidence": 0.88, "place_id": "jk012", "components": {}}
  ]
}

Why this beats a loop

A loop that fires one HTTP request per coordinate adds connection overhead for every row and makes it harder to reason about your daily quota, since you are watching headers scroll past on hundreds of separate responses instead of one. A single bulk call still charges one request per item, so the total cost against your allowance is identical, but you get one set of quota headers to read and one place to catch errors.

Reading the response

Each result in the array lines up with the coordinate you sent at the same position. If a point falls somewhere with no nearby address, such as open water or a large unmapped area, expect a lower confidence score or a coarser precision value rather than an error, so check both fields before you use the formatted address in anything customer facing.

A second example: pairing with time zone data

A common follow-up once you have addresses for a list of coordinates is finding out what time it is at each one. Rather than looping over the results a second time, pass the same coordinate list to /v1/timezone as its own bulk request. You end up with two aligned arrays, addresses from /v1/reverse and time zone identifiers from /v1/timezone, both in the original row order, at a cost of one request per point per endpoint.

A mistake worth avoiding

Do not assume every coordinate in your table is valid before you send it. A latitude outside -90 to 90 or a longitude outside -180 to 180, which happens more often than it should when columns get swapped in a spreadsheet, still counts as a request even though it cannot return a sensible result. Sanity check the ranges in your own code before the batch goes out, rather than paying for a lookup that was never going to succeed.

Sizing your batches

There is no need to send an entire database table in one request. Group coordinates into batches sized for your own script's memory and timeout limits, and keep track of how many requests each batch uses against the free daily allowance or your credit balance. The X-Quota-Used and X-Quota-Free-Remaining headers on each response tell you exactly where you stand before you send the next batch.

Reverse geocoding a full list this way turns what used to be a slow loop into one request per batch, with the API doing the same per-item work either way. Full request and response details are in the reverse geocoding docs.

More in Guides