Batch Geocoding in Python

Python is a widely used programming language for data processing, automation, and geospatial analysis. One common geospatial task is geocoding—translating addresses into geographic coordinates for use in maps, spatial analysis, and location-based services.

Geoapify provides flexible geocoding options depending on your use case:

• For small volumes or real-time lookups, the Geoapify Geocoding API supports synchronous, single-address requests. See our Python tutorial for more.
• For large datasets, the Geoapify Batch Geocoding Endpoint offers an efficient, asynchronous way to geocode up to 1000 addresses per request.

In this article, we’ll focus on batch geocoding in Python using the asynchronous endpoint. But first, let’s compare the two approaches and help you choose the best one for your needs.

Geocoding One Address vs. Batch Geocoding

Geoapify offers two dedicated endpoints to support different geocoding workflows in Python:

• The Standard Geocoding API for synchronous, single-address requests
• The Batch Geocoding API for asynchronous bulk processing

Both approaches convert addresses into geographic coordinates but differ in execution style, performance, and scalability.

Single Address Geocoding

The Standard Geocoding API geocodes one address at a time and returns results immediately. If there are multiple matches, it returns address suggestions. This synchronous method is ideal for real-time applications like user input forms, interactive maps, or autocomplete fields.

You can learn how to implement this in our Python guide for single-address geocoding →

Batch Geocoding

Batch geocoding processes multiple addresses in a single asynchronous request. You submit a job with up to 1000 addresses, and the results become available once processing is complete.

Geoapify’s Batch Geocoding Endpoint is designed to use the system's spare processing capacity, which allows it to handle requests more efficiently—you can geocode up to twice as many addresses for the same cost compared to individual requests. This makes it a great option when processing large datasets where speed and pricing matter.

Key Differences at a Glance

In the next section, we'll walk through how to use the Geoapify Batch Geocoding API in Python—including data preparation, job submission, status checking, and result handling.

Geocode a Batch of Addresses in Python

The Geoapify Batch Geocoding API makes it easy to geocode many addresses at once. Instead of sending requests one by one, you can send up to 1000 addresses in a single request. The job is processed in the background, and you can download the results once it’s finished.

Batch jobs run using spare system resources, which makes them more cost-efficient—you can geocode twice as many addresses for the same price as individual requests. Just keep in mind that processing may take anywhere from a few seconds to a few hours, depending on system load.

You can find a working code example in our GitHub repository.

Setting Up Your Environment

Before running the batch geocoding script, make sure your Python environment is properly set up.

1. Install Python

Ensure you have Python 3.7 or higher installed. You can download it from python.org.

2. Create a Virtual Environment (Optional but Recommended)

Using a virtual environment helps isolate project dependencies:

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate

3. Install Required Packages

Install the requests library, which is used to call the Geoapify API:

pip install requests

4. Save and Run the Code

1. Create a new Python file, e.g. batch_geocode.py, and paste the script into it.
2. Replace "YOUR_API_KEY" in the script with your actual Geoapify API key.
3. Run the script in your terminal:

python batch_geocode.py

You’ll see job status messages printed to the terminal, followed by your geocoding results once the batch is processed.

Step-by-Step: Batch Geocoding with Python

Here's how you can send a batch of addresses and get the results using Python and the requests library:

import requests
import time

# Your Geoapify API key
apiKey = "YOUR_API_KEY"

# Time to wait between attempts (in seconds)
timeout = 1

# How many times to try checking the results
maxAttempts = 10

def geocode_batch(addresses):
    # Send a batch geocoding job
    url = f"https://api.geoapify.com/v1/batch/geocode/search?apiKey={apiKey}"
    response = requests.post(url, json=addresses)

    if response.status_code != 202:
        print("Failed to create the job. Check the input data.")
        return

    jobId = response.json()["id"]
    results_url = f"{url}&id={jobId}"
    print(f"Job submitted. Waiting for results (Job ID: {jobId})...")

    time.sleep(timeout)
    return fetch_results(results_url, attempt=0)

def fetch_results(url, attempt):
    # Poll for job results
    response = requests.get(url)

    if response.status_code == 200:
        print("Job completed. Here are the results:")
        return response.json()
    elif response.status_code == 202 and attempt < maxAttempts:
        print(f"Still processing... (Attempt {attempt + 1})")
        time.sleep(timeout)
        return fetch_results(url, attempt + 1)
    else:
        print("Results not ready. You can check later at:")
        print(url)

# Example addresses
addresses = [
    "668 Cedar St, San Carlos, CA 94070, USA",
    "545 SW Taylor St, Portland, OR 97204, USA",
    "1415 SW Park Ave, Portland, OR 97201, USA",
    "1019 SW Morrison St, Portland, OR 97205, USA",
    "400 SW 6th Ave, Portland, OR 97204, USA"
]

geocode_batch(addresses)

What’s Happening in the Code

• Step 1: Send a list of addresses to the batch API.
• Step 2: Receive a Job ID if the submission is successful.
• Step 3: Poll the result URL until the job is complete.
• Step 4: Once ready, print or process the results.
• Step 5: If the job takes too long, a fallback URL is shown for checking later.

Tip: Adjust the timeout and maxAttempts for larger jobs.

Example Output

After running the batch geocoding job, the results will include detailed information for each address. Here’s a simplified example showing the most important fields from the response:

[
  {
    "query": {
      "text": "668 Cedar Street, San Carlos, CA 94070, United States of America"
    },
    "formatted": "668 Cedar Street, San Carlos, CA 94070, United States of America",
    "lat": 37.502683380952384,
    "lon": -122.26380104761905,
    "confidence": 1,
    "result_type": "building",
    "timezone": {
      "name": "America/Los_Angeles",
      "abbreviation_STD": "PST",
      "abbreviation_DST": "PDT"
    }
    // more fields, incliding structured address: housenumber, street, city, postcode, state, country
  },
  ...
]

You can access many more details in the response, such as address_line1, plus_code, rank, and datasource metadata. To see the full structure, explore the complete Geoapify Geocoding API documentation.

More Geocoding Options

The Geoapify Geocoding API supports a variety of parameters to fine-tune your results—especially useful when working with free-form or ambiguous addresses.

By default, the API searches globally, but you can improve accuracy and reduce ambiguity by narrowing the scope using filters and location bias.

Useful Input Parameters

• filter – Restrict results to a specific country, state, region, or city.
• bias – Prioritize results near a reference point (coordinates, bounding box, etc.).
• type – Specify the kind of location you expect (e.g., city, street, building, etc.).
• lang – Set the language for returned addresses using ISO 639-1 codes (e.g., en, de, fr).

These parameters are supported in both single-address and batch geocoding workflows. You can find the full list of options and formats in the Geoapify Geocoding API documentation.

Additional Capabilities

The Geoapify platform provides more than just forward geocoding. You can also:

• Use Reverse Geocoding to convert coordinates into addresses.
• Search for Places by category (e.g., restaurants, schools, ATMs).
• Get Routes and Directions for driving, walking, cycling, and more.

These tools integrate easily with the batch geocoding workflow if you're building a larger location-based service or analysis pipeline.

Conclusion

Geocoding lets you turn address data into precise geographic coordinates—and with Geoapify’s Geocoding API, it's easy to do this at scale or in real time.

Whether you need to geocode a single address or thousands, the API provides simple and flexible endpoints. With just a few lines of Python using the requests library, you can submit and retrieve results for both synchronous and batch geocoding workflows.

Thanks to the generous Free Plan (up to 6000 addresses/day), Geoapify offers an accessible and cost-effective solution for developers working with location data of any size.

Ready to start? Sign up for a free API key and try batch geocoding in your own project today.

FAQ