Geocodio provides a compatibility endpoint that accepts Google Maps Geocoding API-style requests, making it easy to migrate from Google Maps to Geocodio. If you're already using Google Maps SDKs, you can continue using them by simply changing the API endpoint and your API key.
This compatibility layer returns responses in Google Maps' format, allowing you to keep your existing response handling code completely unchanged. The endpoint supports both forward and reverse geocoding with the same request parameters you're already familiar with.
For new integrations, we recommend using the native Geocodio API to access our full feature set, including data appends and batch geocoding.
The compatibility endpoint at https://api.geocod.io/maps/api/geocode/json is a direct drop-in replacement for Google Maps' geocoding endpoint. Simply change the host from maps.googleapis.com to api.geocod.io and use your Geocodio API key instead of your Google API key.
The endpoint translates your Google Maps-formatted requests into Geocodio queries and returns results in the exact Google Maps response format, so all your existing response handling code continues to work unchanged.
You can continue using official Google Maps SDKs with minimal code changes.
# Forward geocoding
curl "https://api.geocod.io/maps/api/geocode/json?address=1109+N+Highland+St,+Arlington+VA&key=YOUR_GEOCODIO_API_KEY"
# Reverse geocoding
curl "https://api.geocod.io/maps/api/geocode/json?latlng=38.886665,-77.094733&key=YOUR_GEOCODIO_API_KEY"
# Install: pip install googlemaps
import googlemaps
# Create client with Geocodio endpoint
gmaps = googlemaps.Client(
key='YOUR_GEOCODIO_API_KEY',
base_url='https://api.geocod.io'
)
# Forward geocoding
geocode_result = gmaps.geocode('1109 N Highland St, Arlington VA')
location = geocode_result[0]['geometry']['location']
print(f"Lat: {location['lat']}, Lng: {location['lng']}")
# Reverse geocoding
reverse_result = gmaps.reverse_geocode((38.886665, -77.094733))
print(reverse_result[0]['formatted_address'])
// Install: npm install @googlemaps/google-maps-services-js
const { Client } = require("@googlemaps/google-maps-services-js");
const client = new Client({});
// Forward geocoding
const response = await client.geocode({
params: {
address: "1109 N Highland St, Arlington VA",
key: "YOUR_GEOCODIO_API_KEY"
},
url: "https://api.geocod.io/maps/api/geocode/json"
});
const location = response.data.results[0].geometry.location;
console.log(`Lat: ${location.lat}, Lng: ${location.lng}`);
// Reverse geocoding
const reverseResponse = await client.reverseGeocode({
params: {
latlng: "38.886665,-77.094733",
key: "YOUR_GEOCODIO_API_KEY"
},
url: "https://api.geocod.io/maps/api/geocode/json"
});
console.log(reverseResponse.data.results[0].formatted_address);
The compatibility endpoint includes the following Google Maps response fields:
| Feature | Status | Notes |
|---|---|---|
address_components |
✅ Supported | Typed address component arrays (see details below) |
formatted_address |
✅ Supported | Full formatted address string |
geometry.location |
✅ Supported | Latitude and longitude coordinates |
geometry.location_type |
✅ Supported | Accuracy indicators (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, APPROXIMATE) |
geometry.viewport |
✅ Supported | Bounding box for the result |
types |
✅ Supported | Result type indicators |
partial_match |
✅ Supported | Added when accuracy < 1.0 |
status |
✅ Supported | Response status codes (OK, ZERO_RESULTS, etc.) |
The endpoint transforms Geocodio's address data into Google Maps format with these component types:
street_number - House or building numberroute - Complete street name (includes predirectional like N/S/E/W, street name, suffix like St/Ave, and postdirectional like NW/SE)locality - City nameadministrative_area_level_2 - County nameadministrative_area_level_1 - State or province with full name expansion (e.g., VA → Virginia, ON → Ontario, QC → Quebec)country - Country code and full namepostal_code - ZIP or postal codeThe endpoint supports the components parameter for filtering results by specific criteria:
# Filter by country
?components=country:US
# Filter by postal code
?components=postal_code:22201
# Combine multiple filters
?components=country:US|postal_code:22201
Supported component filters:
country:XX - Filter by country code (US, CA)postal_code:XXXXX - Filter by postal codelocality:City - Filter by city nameadministrative_area:State - Filter by state/provinceroute:Street - Filter by street nameCoverage: This endpoint supports US and Canadian addresses only. Requests for addresses in other countries will return a
ZERO_RESULTSstatus.
There are some differences from the Google Maps API that you should be aware of:
place_id is returned but always empty. plus_code is not included in responsesgeometry.viewport field is provided but approximated, not based on actual address boundariescountry, postal_code, locality, administrative_area, and route filters are supported. Other component types are ignoredbounds and region parameters are not supported and will be ignored if providedAll responses return HTTP 200 status codes with error details in the response body's status field, matching Google Maps' behavior.
While the compatibility endpoint makes migration easy, we recommend using the native Geocodio API for new integrations. The native API provides:
You can use both APIs with the same Geocodio account and API key - perfect for gradual migration.