Bulk (batch) geocoding converts many addresses or places to coordinates in a single API call instead of one request per address. The Stadia Maps Bulk Geocoding API accepts up to 5,000 forward or structured geocoding queries per HTTP request, streams results back as they complete, and consumes the same per-query credits as individual requests, with no extra fees.

Since we launched our geocoding product, we've learned a lot about what developers need to build applications that convert addresses, places, and more to coordinates. While we've always supported forward, reverse, and structured queries, one thing we haven't supported is making multiple queries in one request.

Bulk (also known as batch) geocoding makes it faster and simpler to geocode many addresses at once. Whether supporting a batch job or improving performance for multiple simultaneous requests, our new Bulk Geocoding API helps developers build more efficient solutions using the same high-quality Geocoding API they already know.

How Many Addresses Can You Geocode in One Request?

With the new API, you can make up to 5,000 geocoding queries with a single HTTP request. Both forward geocoding and structured geocoding are supported. You can even combine multiple request types in a single bulk request!

Using the bulk endpoint instead of individual requests will make your queries faster. The endpoints' internal parallelization will simultaneously improve throughput, reduce total latency, and simplify the calling code.

This new endpoint is useful in environments without easy access to lightweight concurrency and connection pooling, where each request incurs the connection establishment overhead. Older web frameworks, lower-level code, and shell scripts will especially benefit from using the bulk endpoint instead of the standard endpoints.

For particularly latency-sensitive applications, you can also process the results as they are produced. The endpoint streams the results back as a JSON body, enabling a much lower time-to-first-result if required.

How Much Does Bulk Geocoding Cost?

Bulk geocoding is available for all accounts subscribed to our Standard and Professional plans. Each request consumes credits as if you made a request to the underlying endpoint directly, so there are no additional fees or credits used.

You can find out how many credits each API call consumes in our credit schedule.

Which SDKs and Languages Support Bulk Geocoding?

As usual, our official SDKs have already been updated to support the new API.

You can access it from JavaScript, Python, Kotlin, Swift or PHP without writing any new network or parsing code!

You can even find a curl example in our API documentation so your shell scripts aren't left behind.

Getting Accurate Results at Scale

Sending 5,000 addresses at once raises a question you don't have to think about with single requests: how do you know the results are any good?

Our guide to getting accurate results at scale with bulk geocoding walks through preparing your data, deciding between structured and unstructured queries, running a test batch first, and reading the match_type field to spot problems before you process the whole dataset. It includes Python sample code.

The short version: start with a small, diverse sample, check what proportion of results come back as fallback rather than exact, and fix your input format before you run the full job.

Frequently Asked Questions

How many addresses can you geocode in one bulk request?

Up to 5,000 geocoding queries per HTTP request on the Stadia Maps Bulk Geocoding API. Forward geocoding and structured geocoding are both supported, and you can combine multiple request types in a single bulk request. Results stream back as a JSON body as they are produced, so latency-sensitive applications can process them without waiting for the full batch.

How much does bulk geocoding cost?

Each query in a batch consumes credits as if you had called the underlying endpoint directly, so batching costs no more than making the requests individually. There are no additional fees and no extra credits for using bulk mode. Bulk geocoding is available on the Standard and Professional plans. See the Stadia Maps credit schedule for the per-endpoint credit costs.

Should you use structured or unstructured search for bulk geocoding?

Stadia Maps usually recommends structured search when possible, because it puts you in control of how address components are interpreted. If your data came from a form with separate fields that were joined together, it is effectively already structured. If it came from free-form user input, treat it as unstructured and send it as-is rather than trying to split it apart. The bulk geocoding guide covers how to decide.

How do you check that bulk geocoding results are accurate?

Check the match_type field on each result. An exact match means the address was found. An interpolated result means the house number was estimated along a known street. A fallback result means only a broader component such as the street or city could be matched. If a large proportion of results come back as fallback, the input data or the request format usually needs attention. Run a small diverse sample before processing the full dataset.

Can you combine forward and structured queries in one bulk request?

Yes. A single bulk request can contain a mix of forward geocoding and structured geocoding queries. This is useful when part of your dataset has clean separated fields and part of it is free-form text.

Which SDKs support bulk geocoding?

The official Stadia Maps SDKs for JavaScript, Python, Kotlin, Swift, and PHP all support the Bulk Geocoding API, so you do not need to write network or parsing code yourself. A curl example is included in the API documentation for shell scripts.

Which Stadia Maps plans include bulk geocoding?

Bulk geocoding is available to accounts on the Standard and Professional plans. Because results from bulk jobs are typically written to a database, note that permanent storage of geocoding results also requires an active Standard, Professional, or Enterprise subscription.

Learn More & Next Steps