Drop-in compatibility

You do not have to learn this API to use it. For seventeen other geocoding and IP lookup APIs we run a host that accepts that provider's request format and answers in that provider's response format, with our data behind it. The same applies to the JavaScript map libraries those providers ship. Migration is a hostname change.

How it works

Each drop-in host is a full implementation of one provider's public HTTP interface: the same paths, the same query parameters, the same JSON field names, nesting and types, the same status vocabulary and the same error shapes. The values are ours. Your client code, your parsing code and your error handling do not change.

1. Change the host. maps.googleapis.com becomes gapi.mygeocode.com, dev.virtualearth.net becomes bing.mygeocode.com, and so on. The table below has every pair.
2. Swap the key, or drop it. Put your My Geocode key in the parameter the old key used (key, apiKey, access_token, token...). Any address gets 2,500 free requests a day with no key, and every key comes with 2,500 of its own, so migrating and testing costs nothing.
3. Compare. Run a sample of real requests against both hosts. Coordinates will differ slightly because the data is different; field names will not.

$ curl "https://maps.googleapis.com/maps/api/geocode/json?address=10+Downing+St+London&key=GOOGLE_KEY"

$ curl "https://gapi.mygeocode.com/maps/api/geocode/json?address=10+Downing+St+London&key=MYGEOCODE_KEY"

All drop-in hosts

Every host runs on the same infrastructure, the same data, the same free allowance and the same prices as api.mygeocode.com. Click a provider for its endpoint list, a sample response and the known differences.

JavaScript map libraries

Provider changes hurt most in the browser, where the map, the geocoder widget and the billing are tangled together. For the libraries below, the library itself is loaded from our host (or, for MapLibre, Mapbox GL and Leaflet, pointed at our host by configuration) and keeps its public API: google.maps.Map, Microsoft.Maps.Map, H.Map and the rest. Tiles, geocoding, autocomplete and elevation come from us. Map loads and tiles are free; geocoding calls count as usual.

The JavaScript drop-ins page has the before-and-after snippets, the list of what is and is not included for each library, and the tile and style URLs.

Where the key goes

Each host accepts the key in the place the original provider expects it, and also in the X-API-Key header. A key is optional: 2,500 requests a day per address need none. A free one takes a minute to get and adds credit, packages and a usage history. A pay-as-you-go key may be used from two IP addresses per rolling 24 hours and an Unlimited key from three; use more keys or packages for more addresses (see authentication).

Quota and errors on the drop-in hosts

The daily allowance is the same as everywhere else and is counted per key, or per address when no key is sent, across api.mygeocode.com and every drop-in host: 2,500 free a day, then credit or an Unlimited key. The X-Quota-* and X-Key-IPs-* headers are sent on every host, so you can read the true state from the headers whatever the body format. In the body, limits are reported the way the provider reports them:

What matches and what does not

Migration checklist

1. Search your code and configuration for the provider's hostname. It is often in more than one place: server code, mobile apps, a CDN rule, a cached config.
2. Change it to the drop-in host from the table above. Keep the path.
3. Replace the key with a My Geocode key. Use one key per server or two at most; a pay-as-you-go key accepts two IP addresses per rolling 24 hours, an Unlimited key three.
4. Run your existing test suite. It should pass unchanged. If a field you depend on is absent, check the host's page for known gaps and tell us.
5. Replay a few hundred real requests against both hosts and compare coordinates and the fields you display. Look at precision where the drop-in exposes it (as location_type, accuracy, resultType and so on).
6. Watch X-Quota-Used for a day to size your plan: credit below about 19,000 requests a day, an Unlimited key above.
7. Cancel the old billing.

Provider SDKs

Most official client libraries accept a custom base URL, so they work with the drop-in hosts too: the Google Maps Services clients (googlemaps for Python, @googlemaps/google-maps-services-js), the Mapbox SDKs (origin option), HERE's REST clients, ipinfo's libraries and Nominatim wrappers such as geopy (domain=). Point them at the host from the table and pass your My Geocode key where the provider key went.

A provider that is not listed

Adding a host is a few days of work when the provider's format is documented. If you are on a service that is not here, say which one and roughly how many requests a day you send. Recent additions were all requests from users.