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.

How It Works

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.

Using Google Maps SDKs with Geocodio

You can continue using official Google Maps SDKs with minimal code changes.

Shell/curl

# 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"

Python

# 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'])

JavaScript (Node.js)

// 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);

What's Supported

The compatibility endpoint includes the following Google Maps response fields:

Supported Address Components

The endpoint transforms Geocodio's address data into Google Maps format with these component types:

• street_number - House or building number

• route - Complete street name (includes predirectional like N/S/E/W, street name, suffix like St/Ave, and postdirectional like NW/SE)

• locality - City name

• administrative_area_level_2 - County name

• administrative_area_level_1 - State or province with full name expansion (e.g., VA → Virginia, ON → Ontario, QC → Quebec)

• country - Country code and full name

• postal_code - ZIP or postal code

Supported Countries

• US - United States

• CA - Canada (with proper province expansion)

Component Filtering

The 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 code

• locality:City - Filter by city name

• administrative_area:State - Filter by state/province

• route:Street - Filter by street name

Important Limitations

Coverage: This endpoint supports US and Canadian addresses only. Requests for addresses in other countries will return a status.

There are some differences from the Google Maps API that you should be aware of:

• Empty fields: place_id is returned but always empty. plus_code is not included in responses

• Viewport approximation: The geometry.viewport field is provided but approximated, not based on actual address boundaries

• Limited component filtering: Only country, postal_code, locality, administrative_area, and route filters are supported. Other component types are ignored

• Bounds and region: The bounds and region parameters are not supported and will be ignored if provided

All responses return HTTP 200 status codes with error details in the response body's status field, matching Google Maps' behavior.

Migration Recommendation

While the compatibility endpoint makes migration easy, we recommend using the native Geocodio API for new integrations. The native API provides:

• Data appends: Enrich results with census data, timezones, congressional districts, and more

• Batch geocoding: Process thousands of addresses in a single request

• More detailed parsing: Better address component breakdown and matching

• Higher accuracy: Rooftop-level accuracy for most US addresses

You can use both APIs with the same Geocodio account and API key - perfect for gradual migration.

Related Resources

• API Documentation - Technical details on the compatibility endpoint

• Forward Geocoding Guide - Learn about Geocodio's native geocoding API

• Reverse Geocoding Guide - Convert coordinates to addresses

• Data Appends Overview - Enrich your geocoding results with additional data