August 11, 2025Introducing the Official Geocodio Python Library
Geocodio's new official Python library simplifies geocoding, reverse geocoding, and data appends for US and Canadian addresses with batch processing support, automatic error handling, and easy integration for developers.
Introducing the Official Geocodio Python Library
We're pleased to announce that Geocodio now has an official Python library, making it easier than ever to integrate geocoding, reverse geocoding, and other location data into your Python applications with Geocodio. Whether you're building web applications, data analysis pipelines, or automation scripts, our new library provides a clean, straightforward way to convert addresses and coordinates in high volumes.
If you're already using Geocodio's API, transitioning to the official library is straightforward and will likely simplify your existing code. For new users, it's the recommended way to get started with geocoding data in Python with Geocodio.
Why Use the Official Library?
While you've always been able to work with Geocodio's API directly through HTTP requests, our official Python library streamlines the entire process.
The library takes care of authentication, request formatting, response parsing, and error handling. Instead of writing boilerplate code to manage API calls, you can accomplish the same tasks with just a few lines of clean, readable Python.
What Can You Do With It?
Our Python library supports all the features you rely on from Geocodio:
Forward and Reverse Geocoding: Convert addresses to coordinates or coordinates back to addresses, either one at a time or in batches of up to 10,000 lookups. The library automatically handles the batch processing for you.
Data Appends: Easily add supplementary information like Congressional districts, Census data, timezones, and more to your geocoding results. Simply specify which fields you need, and the library includes them in your response.
List Management: For larger datasets, you can geocode CSV, TSV, or Excel spreadsheets to geocode asynchronously, monitor their progress, and download the completed results when ready.
Automatic Address Parsing: The library intelligently breaks down addresses into their component parts, making it simple to work with standardized address data.
Enterprise Support: If you're using Geocodio Enterprise, the library works seamlessly with your dedicated instance by simply specifying the Geocodio Enterprise hostname.
Making the Switch from Direct API Usage
If you're currently making HTTP requests directly to Geocodio's API, migrating to the official library is more straightforward than you might expect. The library handles the same endpoints you're already familiar with, but eliminates much of the repetitive code.
Here's how a typical migration looks:
Before (direct HTTP requests):
import requests
import json
url = "https://api.geocod.io/v1.7/geocode"
params = {
'q': '1600 Pennsylvania Ave, Washington, DC',
'api_key': 'YOUR_API_KEY',
'fields': 'cd,timezone'
}
response = requests.get(url, params=params)
data = json.loads(response.text)
print(data['results'][0]['formatted_address'])
After (using the official library):
from geocodio import Geocodio
client = Geocodio("YOUR_API_KEY")
response = client.geocode(
"1600 Pennsylvania Ave, Washington, DC",
fields=["cd", "timezone"]
)
print(response.results[0].formatted_address)
The library handles JSON parsing, error checking, and response formatting automatically. Your existing logic remains the same, but now you're working with cleaner, more maintainable code.
Error handling becomes much simpler too. Instead of checking HTTP status codes and parsing error messages from JSON responses, you can catch specific exception types:
from geocodio import Geocodio
from geocodio.exceptions import AuthenticationError, InvalidRequestError
try:
client = Geocodio("YOUR_API_KEY")
response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
except AuthenticationError:
print("Check your API key")
except InvalidRequestError:
print("Invalid address format")
Response structure is also more intuitive. While the underlying API response remains the same, the library provides convenient object properties instead of dictionary keys. You'll access response.results[0].formatted_address rather than data['results'][0]['formatted_address'], making your code more readable and less prone to typos.
For batch operations, the improvement is even more noticeable. Instead of managing multiple HTTP requests and combining responses, you can process thousands of addresses with a single method call. (Keep reading for examples.)
Getting Started is Simple
Installation is as straightforward as you'd expect from Geocodio:
pip install geocodio-library-python
Once installed, you can start geocoding immediately:
from geocodio import Geocodio
# Initialize with your API key
client = Geocodio("YOUR_API_KEY")
# Geocode a single address
response = client.geocode("1600 Pennsylvania Ave, Washington, DC")
print(response.results[0].formatted_address)
Geocodio has two options for large batches: the batch endpoint and the lists endpoint.
Let's start with the batch geocoding endpoint:
addresses = [
"1600 Pennsylvania Ave, Washington, DC",
"1 Infinite Loop, Cupertino, CA"
]
batch_response = client.geocode(addresses)
for result in batch_response.results:
print(result.formatted_address)
Next, to geocode a CSV, TSV, or Excel spreadsheet via API:
with open("addresses.csv", "rb") as f:
new_list = client.create_list(
file=f,
filename="addresses.csv",
direction="forward"
)
# Check the processing status
list_details = client.get_list(new_list.id)
print(f"Processing status: {list_details.status}")
# Download results when complete
if list_details.status and list_details.status.get("state") == "COMPLETED":
file_content = client.download(new_list.id, "results.csv")
print("Results downloaded successfully")
Built for Reliability
We understand that when you're building applications, you need to handle errors gracefully. The library includes specific exception types for different scenarios—authentication issues, invalid requests, and server errors—so your integration can respond appropriately to each situation.
The library also includes comprehensive documentation and examples to help you implement exactly what you need, whether that's a simple address lookup or complex batch processing with multiple data appends.
Perfect Time to Explore New Features
If you're currently using Geocodio through direct API calls, switching to the official library is an ideal time to try features that may not have been available when you first integrated Geocodio.
Data Enrichment: Beyond basic geocoding, you can append dozens of additional data points to your addresses and coordinates all in the same API request. Add Congressional districts, Census household income, school districts, timezones, and much more with a simple fields parameter. This data enrichment can transform a simple address lookup into comprehensive location intelligence.
Spreadsheet Geocoding via API: The Lists API, introduced in 2022, allows you to geocode large datasets more efficiently. Upload CSV files with hundreds of thousands or even millions of addresses, let Geocodio process them in the background, and download the enriched results when ready. The lists useful for both one-time data migrations and regular batch jobs.
Latest API Features: The library automatically uses our most current API version, ensuring you have access to the latest improvements in accuracy, performance, and available data appends. See our API version history here.
Ready to Try It?
The official Geocodio Python library is now available on PyPI and ready to use in your projects. You'll find complete documentation, code examples, and implementation guides at https://www.geocod.io/docs/?python.
The library is open source and hosted on GitHub, where you can also report issues or contribute improvements.
The friendly, human Geocodio team is ready to help with any questions or thoughts you might have: support@geocod.io.
We're excited to see what you'll build with it!