Guides | My Geocode blog

Monitor your key's usage before you hit a limit

2026-09-21T18:22:00+00:00

Finding out you are near your daily limit because a request just got rejected is the least useful way to find out. Every response already carries the numbers needed to see it coming.

The headers to watch

X-Quota-Limit: 2500
X-Quota-Used: 2210
X-Quota-Free-Remaining: 290
X-Quota-Network-Used: 2210
X-Credits-Remaining: 5.75
X-Key-IPs-Used: 2
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00Z

X-Quota-Free-Remaining shrinking toward zero is your clearest early signal for the free daily allowance. X-Credits-Remaining tells you how much runway is left once you have moved past the free allowance and are drawing on prepaid credit at €0.0001 a request.

Setting your own alert threshold

Rather than waiting for a 429, log or alert once X-Quota-Free-Remaining drops below a threshold you choose, such as 10 percent of X-Quota-Limit, so there is time to react, whether that means slowing down a batch job, topping up credit, or simply expecting a quiet period until X-Quota-Reset.

Watching key IP slots too

X-Key-IPs-Used and X-Key-IPs-Limit track how many different source addresses have used a given key under its rolling IP slot allowance. A key suddenly used from more addresses than expected, climbing toward its limit, is worth investigating on its own, separate from request volume, since it can point to a key being shared more widely than intended.

Building a simple dashboard

A small script that logs these headers on a sample of requests, or on every request if volume is low enough, gives you a usage trend over time without needing a separate monitoring call, since the numbers arrive on responses you were already making. Plotting X-Quota-Used against time across a day or a week shows usage patterns that a single snapshot never would.

Acting before you hit the wall

Once you see a consistent pattern of running close to your limit, the two paths forward are the same two options available at any point: add prepaid credit for occasional overflow, or move to an Unlimited key at €50 a month if you are consistently past the free allowance. Either decision is easier to make calmly, ahead of time, than in response to a live 429 blocking real traffic.

Reading quota headers as routine telemetry, not just as something to check when a request fails, turns a hard limit into a manageable trend. Current allowance and credit options are on the pricing page, and full header definitions are on the rate limits docs.

Cross-check an address against its postal code

2026-09-21T07:33:00+00:00

A customer can type a real street address and a real postal code that do not actually belong together, most often by transposing digits or copying an old postal code into a new address. Neither field alone reveals the problem, since both are individually valid.

Resolving each field independently

Geocode the full address with /v1/forward to see what postal code it actually resolves to, and separately look up the postal code the customer typed with /v1/postcode to see what area it covers.

GET /v1/forward?q=10 Downing Street, London&limit=1

{
  "status": "ok",
  "results": [
    {"formatted": "10 Downing Street, London, UK", "lat": 51.5033, "lon": -0.1276, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "op678", "components": {"postcode": "SW1A 2AA", "city": "London"}}
  ]
}

GET /v1/postcode?code=SW1A 1AA&country=GB

{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [{"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London"}}]
}

Comparing the two results

If the postcode component from the address lookup does not match the postal code the customer typed, as in this example, that is a mismatch worth flagging, even though both the address and the postal code independently checked out as real. Comparing the two components directly is more reliable than comparing distance between the two sets of coordinates, since a postal code area can be small enough that even a genuine match will not sit exactly on the address's coordinates.

A second example: a bigger mismatch worth catching earlier

The same check also catches a far more obvious error, a postal code entered for an entirely different country or region than the street address itself, such as a UK-format code paired with an address that actually resolves inside another country. Comparing the country component from the address result against the country parameter used for the postcode lookup, before even reaching the more detailed postcode comparison, is a cheap first check that filters out this kind of larger mistake early.

What to do with a mismatch

Show the customer both values side by side and ask them to confirm which one is correct, rather than silently picking one over the other or rejecting the order outright. A transposed digit is an easy fix once pointed out, and a genuine edge case where a postal code legitimately covers a boundary between two commonly used values is rare enough to handle with a quick manual confirmation.

A common mistake to avoid

Do not compare the two sets of coordinates directly with a distance threshold as a substitute for comparing the postcode components themselves. A postal code area can be geographically small enough that even a completely correct match will show some distance between the postcode's representative point and the address's specific building coordinates, and a small area code can also be geographically large enough that a genuinely mismatched pair still falls within a lenient distance threshold. Comparing the postcode text itself is a more direct and reliable check than trying to infer a match from distance.

An edge case worth allowing for

A postal code area that sits right on a boundary between two administrative regions can legitimately return a component set that looks slightly different depending on which endpoint resolved it, even when both are correct. Treat a close but not exact textual match, such as a difference only in how a region name is written, with a lighter touch than a fully different postal code entirely.

Checking many orders at once

For a batch of existing orders rather than a single new submission, both endpoints accept a bulk POST array, so a backlog of orders can be checked by sending the addresses as one bulk request to /v1/forward and the postal codes as another bulk request to /v1/postcode, then comparing the two result arrays by position.

Request cost

This check uses two requests per order, one for the address and one for the postal code, both counted against your daily allowance the same as any other lookup. That is a reasonable cost for catching an error that would otherwise show up as a failed delivery.

Catching a mismatched postal code before an order ships is worth the second request it takes to check. Details on both endpoints are in the forward geocoding docs and the postal code lookup docs.

Add postal code auto-fill to a shipping form

2026-09-20T21:49:00+00:00

A shipping form with separate fields for postal code, city, and region asks a customer to type information that a single postal code often already implies.

Looking up the code

Once a customer finishes typing a postal code and selects a country, or if country is already known from their account, send both to /v1/postcode.

GET /v1/postcode?code=SW1A 1AA&country=GB

{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [
    {"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London", "country": "GB"}}
  ]
}

Filling the form fields

Populate the city and region fields directly from the components object in the result, and let the customer confirm or correct them rather than locking the fields entirely, since a postal code occasionally spans a boundary or covers more than one commonly used place name.

A second example: prefilling a billing region for tax purposes

The same lookup fits a signup or billing form that needs a customer's region for tax calculation purposes, not just a shipping form. Triggering the same postcode lookup once a billing postal code is entered fills the region field consistently in both contexts using the identical request and response shape, so the same client-side and server-side handling code can serve both forms.

Triggering the lookup at the right moment

Run the lookup once the postal code field loses focus, or once it reaches the expected length for the selected country, rather than on every keystroke, since a postal code is only meaningful to look up once it is complete. This keeps the feature to one request per completed field entry rather than one per character typed.

A common mistake to avoid

Do not hard-code a fixed expected length for every country's postal code format. A five-digit assumption that works for one country will trigger the lookup too early or never at all for a country using a different length or an alphanumeric format like the example above. Either trigger on focus loss regardless of length, or maintain a small per-country length table if you want to trigger earlier for countries you support most often.

Handling an unrecognized code

An empty results array means the code was not recognized for that country, most often because of a typo. Leave the city and region fields blank and let the customer fill them in manually rather than blocking form submission, since rejecting the field outright over an auto-fill failure is a worse experience than simply asking for manual entry in that one case.

An edge case: a code covering more than one place name

Some postal codes legitimately cover an area known locally by more than one place name, or sit right at a boundary between two commonly used city names. When this happens, showing the returned value as an editable suggestion rather than a fixed label lets the customer correct it to whichever name they actually use, without treating either as more or less official than the other.

Getting exact coordinates once the address is complete

Auto-fill from a postal code gives an area-level location, which is enough for city and region fields, but once the customer has typed a full street address on top of that, running the complete address through /v1/forward gets you the precise coordinates a shipping label or delivery routing system actually needs.

What it costs

Each completed postal code field triggers one request. A shipping form processing many orders a day still uses this feature at a modest rate, one lookup per order rather than per keystroke, keeping it well within the 2,500 free requests a day included with every key for most stores.

Auto-filling city and region from a postal code cuts a shipping form down by two fields for the large majority of customers who type a valid code. Full field definitions are on the postal code lookup docs.

Build a heatmap from raw IP address logs

2026-09-20T09:25:00+00:00

An access log full of IP addresses has real geographic information buried in it, but only once each address has been resolved to coordinates that a mapping tool can actually plot.

Extracting addresses from the log

Pull the unique IP addresses out of your log file first, rather than looking up every single log line individually, since the same visitor address commonly appears many times across a session and there is no reason to pay for the same lookup repeatedly.

sort logfile.txt | awk '{print $1}' | sort -u > unique_ips.txt

Resolving in bulk

Send the list of unique addresses as a bulk POST array to /v1/ip.

POST /v1/ip
Content-Type: application/json

["203.0.113.10", "198.51.100.25", "192.0.2.44"]

{
  "status": "ok",
  "results": [
    {"ip": "203.0.113.10", "version": 4, "found": true, "country": "Germany", "country_code": "DE", "region": "Berlin", "city": "Berlin", "postcode": "10115", "lat": 52.5300, "lon": 13.3800, "timezone": "Europe/Berlin", "asn": 1111, "org": "Example ISP"},
    {"ip": "198.51.100.25", "version": 4, "found": true, "country": "Spain", "country_code": "ES", "region": "Madrid", "city": "Madrid", "postcode": "28001", "lat": 40.4168, "lon": -3.7038, "timezone": "Europe/Madrid", "asn": 2222, "org": "Example Networks"},
    {"ip": "192.0.2.44", "version": 4, "found": false}
  ]
}

Building the heatmap dataset

Pair each returned lat and lon with the frequency count of that original address in your log, so a visitor who appears a hundred times in the log contributes proportionally more weight than one who appears once. Feed the resulting list of weighted coordinate points into whichever mapping or charting tool you use to render the heatmap.

A second example: a country-level breakdown instead

If a precise point-by-point heatmap is more detail than you need, aggregating by country_code instead of raw coordinates produces a simpler choropleth-style view, one figure per country rather than a scattered cloud of points. This uses exactly the same bulk lookup, just grouped differently once the results come back, so it costs nothing extra to build both views from the same resolved data.

Handling addresses that do not resolve

An entry with found: false, as in the third result above, should simply be excluded from the heatmap rather than plotted at a default location, since including it would misleadingly cluster unresolved traffic somewhere on the map that has nothing to do with where it actually came from.

A common mistake to avoid

Do not skip filtering out obvious non-visitor traffic, such as internal health checks or monitoring services that hit your server constantly from a fixed address, before building the unique address list. A monitoring service polling every minute can rack up a disproportionate log line count that has nothing to do with real visitor geography, and while deduplication already limits it to one resolved point, that one point can still visually dominate a heatmap out of proportion to any real traffic pattern it represents.

An edge case: hosting and data center traffic

The org field on a resolved address often reveals when traffic is coming from a data center or cloud hosting range rather than a residential or mobile connection, which is a reasonable signal for filtering out bot or scraper traffic before it skews a heatmap meant to represent real visitor locations.

What it costs

Resolving unique addresses rather than every log line is what keeps this affordable, since request cost is one per unique address, not one per log line. A log with a million lines but only a few thousand unique visitor addresses costs a few thousand requests, not a million, comfortably manageable against prepaid credit or an Unlimited package for a large site, and often within the free allowance for a smaller one. Watching the X-Quota-Used header during a large batch job is a simple way to confirm usage is tracking as expected before the job finishes.

Deduplicating before you resolve is the single biggest lever for keeping a log-based heatmap affordable. The IPv4 lookup docs cover the bulk request format in full.

Set sensible timeouts for high-volume batch jobs

2026-09-19T21:44:00+00:00

A timeout value that works fine for a single address lookup will cut off a bulk request carrying a few thousand items well before the server has finished processing all of them, which looks like a failure even though the request would have completed given enough time.

Why bulk requests need more time

Each item in a bulk array is a lookup in its own right, so a request with 2,000 items in it involves roughly 2,000 times the processing of a single lookup, even though it is one HTTP call from your side. A one or two second timeout, reasonable for a single address, is nowhere near enough for a request of that size.

Scaling the timeout to the batch

Set your client's timeout proportionally to the size of the array you are sending, with some margin for typical variation, rather than using a single fixed value across every request your code makes, small or large.

timeout_seconds = max(5, item_count * 0.05)

This is a starting point to tune against your own observed behavior, not a fixed number to treat as authoritative, since actual per-item processing time is not a published guarantee.

Preferring smaller chunks over one giant request

Rather than pushing timeout values higher and higher to accommodate an ever larger single request, split a very large job into chunks of a few hundred to a few thousand items each. Smaller chunks need shorter, more predictable timeouts, and a failure partway through only costs you the current chunk rather than the entire job.

Handling a timeout that does happen

If a request does time out on your end, you may not know whether the server actually finished processing it or not. Rather than blindly resubmitting the same chunk, which could double-count against your quota if the original request did complete, check your quota headers from your most recent successful call to estimate whether the timed-out chunk likely went through, and resubmit cautiously.

Cost is unaffected by timeout settings

A timeout is purely a client-side setting about how long you are willing to wait. It has no effect on what a request costs, still one request per item processed, whether your client waited the full duration or gave up early.

Matching your timeout to your batch size, and preferring several smaller chunks over one very large request, keeps large jobs both reliable and easy to resume if something goes wrong. Chunking and quota strategy for large jobs is covered further on the rate limits docs.

Add server-side geolocation to a Node or PHP app

2026-09-19T09:07:00+00:00

Geolocation belongs on the server for most use cases, personalization, defaults, and analytics among them, since it needs no cooperation from the visitor's browser and no script running client-side at all.

The request itself

Regardless of language, the call is the same plain HTTP GET request to /v1/ip, with the key sent as a header.

GET /v1/ip?ip=203.0.113.60
X-API-Key: mg_live_examplekey123

{
  "status": "ok",
  "ip": "203.0.113.60",
  "version": 4,
  "found": true,
  "country": "Netherlands",
  "country_code": "NL",
  "region": "North Holland",
  "city": "Amsterdam",
  "postcode": "1012",
  "lat": 52.3702,
  "lon": 4.8952,
  "timezone": "Europe/Amsterdam",
  "asn": 3344,
  "org": "Example ISP"
}

In a PHP app

Fetch the visitor's own address from the request, typically $_SERVER['REMOTE_ADDR'], and pass it as the ip parameter, then make the HTTP request using whichever HTTP client your PHP setup already uses, curl or a library wrapper around it. Since this site itself is built as server-rendered PHP with no client-side JavaScript, this pattern fits naturally into a page's normal rendering flow, with the location data available before the page markup is generated.

In a Node app

Read the visitor's address from the incoming request object, commonly req.socket.remoteAddress or a header set by a reverse proxy such as X-Forwarded-For if one sits in front of your app, and make the same GET request using your HTTP client of choice before rendering a response.

Handling a proxy in front of your app

If your app sits behind a load balancer or reverse proxy, the address your code sees directly might be the proxy's own address rather than the visitor's. Check whatever forwarded-address header your proxy sets and pass that address explicitly as the ip parameter, rather than relying on the connection's raw remote address, which would otherwise geolocate your own infrastructure instead of the visitor.

Request cost either way

The lookup itself costs the same one request whether it is called from PHP or Node, or any other backend language, since cost is tied to the request reaching the API, not to what made the call. Cache the result for the length of a session in either language to avoid repeating the lookup on every page.

Server-side geolocation works the same way regardless of backend language, one HTTP call with the visitor's address. Full authentication options are on the authentication docs, and the field list is on the IPv4 lookup docs.

Localize date and time formats using the visitor's time zone

2026-09-18T21:17:00+00:00

A timestamp displayed in your server's time zone reads correctly to almost nobody except whoever happens to sit in that same zone, which for a site with visitors anywhere is close to nobody at all.

Getting the visitor's zone

An IP lookup returns a timezone field directly, giving you the identifier needed to localize any timestamp on the page.

GET /v1/ip?ip=203.0.113.77

{
  "status": "ok",
  "ip": "203.0.113.77",
  "version": 4,
  "found": true,
  "country": "Brazil",
  "country_code": "BR",
  "region": "Rio de Janeiro",
  "city": "Rio de Janeiro",
  "postcode": "20040",
  "lat": -22.9068,
  "lon": -43.1729,
  "timezone": "America/Sao_Paulo",
  "asn": 5566,
  "org": "Example ISP"
}

Converting stored timestamps

Store every timestamp in your database in UTC, as usual, and convert to the visitor's local zone only at display time, on the server, using the timezone identifier you looked up. Since this site renders everything server-side with no client-side JavaScript, the conversion and formatting both happen before the page is sent, not afterward in the browser.

local_time = convert_to_timezone(stored_utc_timestamp, "America/Sao_Paulo")

A second example: an order confirmation timestamp

An order confirmation page showing "placed at" and "expected by" times is a good example of where this matters beyond a simple page header clock. Converting both timestamps through the same visitor zone, rather than leaving one in server time by oversight, keeps the two figures consistent and avoids a confusing situation where the expected delivery time appears to be earlier than the order time because one was converted and the other was not.

Formatting, not just converting

Time zone and format are related but separate choices. A visitor in a zone that commonly uses a 24-hour clock and day-month-year date order benefits from formatting that matches, not just a shifted hour value written in a format that still looks foreign. Pair the country_code from the same IP lookup with a small formatting lookup table if you want to go beyond just adjusting the hour.

A common mistake to avoid

Do not implement the conversion as a fixed hour offset calculated once and applied to every timestamp going forward. A zone's actual offset from UTC can change over the course of the year with daylight saving, so a timestamp converted correctly in one season can come out an hour wrong in another if the code applies a stored offset number rather than converting through the timezone identifier itself using a proper date and time library.

An edge case: non-hour offsets

Not every time zone sits at a whole-hour offset from UTC. Some are offset by 30 or 45 minutes rather than a full hour. Relying on a date library that understands the full IANA time zone identifier, rather than a simplified hour-only offset value, handles this correctly without any special-case code on your part. The utc_offset and abbreviation fields from the timezone lookup docs are useful if you want to display the offset explicitly alongside a converted time.

Caching the zone for a session

Look up the time zone once per visitor session and reuse it for every timestamp rendered on every page during that visit, rather than calling the API again for each individual date shown, since the zone itself does not change mid-session.

Cost of localizing a whole site

One lookup per new session covers localization for every timestamp shown during that visit, one request regardless of how many dates appear on the page. This keeps even a content-heavy site well within the 2,500 free requests a day included with every key.

Getting local time and date formatting right across a whole site comes down to one lookup per session and consistent server-side rendering after that. The IPv4 lookup docs and timezone lookup docs cover both approaches to getting the zone.

Build a simple "nearest office" finder

2026-09-18T08:58:00+00:00

A company with a handful of offices does not need anything elaborate to answer "which office is closest to me," just one geocoding request and a short comparison against a list that rarely changes.

Geocoding the input

Whether the visitor types an address or a postal code, geocode it to get coordinates.

GET /v1/forward?q=Berlin, Germany&limit=1

{
  "status": "ok",
  "results": [
    {"formatted": "Berlin, Germany", "lat": 52.5200, "lon": 13.4050, "type": "locality", "precision": "city", "confidence": 0.85, "place_id": "bl456", "components": {"city": "Berlin", "country": "DE"}}
  ]
}

Comparing against your office list

Keep your office coordinates as a small fixed list in your own code or configuration, since this rarely changes and does not need a lookup of its own each time.

offices = [
  {"name": "Berlin", "lat": 52.5170, "lon": 13.3888},
  {"name": "Paris", "lat": 48.8566, "lon": 2.3522},
  {"name": "London", "lat": 51.5074, "lon": -0.1278}
]

Calculate distance from the visitor's coordinates to each office using a standard haversine formula, then sort by distance and return the closest match.

A second example: adding a type-ahead field

Instead of a plain text box, backing the location field with /v1/autocomplete lets the visitor pick from suggested places as they type, reducing the chance of a typo producing an unexpected geocoding result. Once a suggestion is selected, resolving its place_id or its text through the same forward geocoding flow feeds straight into the same distance comparison already described.

Handling a city-level match

Notice the precision in the example above is "city" rather than "house", since the visitor only entered a city name. That is fine for an office finder, where the goal is picking the nearest office out of a handful of options, not pinpointing an exact building. A coarser precision here does not need special handling the way it might for a delivery address.

A common mistake to avoid

Do not forget to update the fixed office list in your own code when a physical office opens, closes, or moves. Because the list lives in your own configuration rather than in the API, it is easy for it to quietly go stale, silently pointing visitors toward a closed location or leaving a new one out of every comparison entirely. Treat that list as part of your regular content review, not a one-time setup step.

An edge case: an ambiguous place name

A short place name can occasionally match more than one real location, such as a place name shared between a country and an unrelated region elsewhere. Passing the countries parameter to restrict candidate matches to the countries where you actually operate offices avoids this kind of ambiguity resolving to the wrong side of the world entirely.

Displaying more than just the nearest one

Showing the two or three closest offices, rather than only the single nearest one, gives a visitor near a regional boundary the chance to pick the one that actually suits them, such as one with a language or time zone that fits better even if it is a little farther by distance.

What it costs

Each search is one geocoding request. The comparison against your office list happens entirely in your own code afterward and adds nothing further to your request count. A page like this, even with steady traffic, stays well inside the 2,500 free requests a day included with every key.

A nearest office finder built this way needs exactly one request per visitor search, with the actual comparison logic living entirely on your side. Details on the request format are in the forward geocoding docs.

Geocode addresses that include apartment or unit numbers

2026-09-17T20:44:00+00:00

An apartment number added onto a street address is a normal part of a lot of real addresses, and it is worth understanding how a geocoding lookup handles it rather than stripping it out before sending the request, which is a common but unnecessary habit.

Sending the full address

Include the apartment or unit number as part of the free-text query, the same as any other part of the address.

GET /v1/forward?q=Apt 4B, 350 Fifth Avenue, New York&limit=1

{
  "status": "ok",
  "query": "Apt 4B, 350 Fifth Avenue, New York",
  "results": [
    {
      "formatted": "350 Fifth Avenue, New York, NY",
      "lat": 40.7484,
      "lon": -73.9857,
      "type": "address",
      "precision": "house",
      "confidence": 0.95,
      "place_id": "es234",
      "components": {"house_number": "350", "street": "Fifth Avenue", "city": "New York", "region": "NY", "country": "US"}
    }
  ]
}

Why the unit number does not appear in coordinates

Coordinates from a geocoding lookup identify a building, not a specific unit within it, since individual apartments do not have their own separate mapped location the way a building does. The apartment or unit portion of an address is not expected to change the lat and lon values, and its absence from the components object is expected too, not a sign that the input was ignored or mishandled.

A second example: a suite number in a commercial building

The same pattern holds for a business address with a suite or floor number.

GET /v1/forward?q=Suite 200, 1 Example Plaza, Chicago&limit=1

A large office building housing dozens of separate businesses still geocodes to one set of building coordinates regardless of which suite is named in the query, exactly as an apartment building does. Anything distinguishing one tenant from another within that building needs to live in your own records, not in the coordinates.

A common mistake to avoid

Do not try to work around the missing unit component by appending it onto the postcode or another component field yourself after the fact, such as writing a postal code as "20500 Apt 4B". Doing this corrupts a field that other systems, including your own validation and any downstream address lookups, expect to contain only a real postal code. Keep the unit number in its own field entirely separate from every geocoded component.

Storing the unit number separately

Rather than folding the unit number into the address string you geocode every time, store it as its own field in your own data model alongside the geocoded building address. This keeps the geocoding request focused on what actually affects the result, the building's location, while still preserving the unit information for delivery labels or internal records.

When it matters for delivery

A courier or postal service needs the unit number for actual delivery, even though it played no role in the coordinates. Keep both pieces, the geocoded building coordinates and the separately stored unit number, together in the final delivery record so nothing gets lost in the process.

An edge case worth knowing

A single building address can house a large number of separate residents or tenants, all sharing the same coordinates and the same postal code lookup result. If you are cross-checking a customer's postal code against a forward geocoded address, as covered in the postal code cross-check guide, remember that this many-to-one relationship between units and a building is expected and is not itself a sign of a data problem.

Cost is unaffected

Whether or not an address includes an apartment or unit number, the lookup still costs one request, the same as any other forward geocoding call.

Including a unit number in the query does no harm, and stripping it out is not necessary for accurate geocoding, though separating it into its own stored field afterward keeps your data cleaner. See the forward geocoding docs for the full components list.

Add a distance-from-store calculator to a landing page

2026-09-17T09:15:00+00:00

"How far is your nearest location from me" is a question a landing page can answer directly instead of sending a visitor off to a separate map to figure out themselves.

Geocoding the visitor's input

Take whatever address or postal code the visitor types into a simple form field and geocode it.

GET /v1/forward?q=350 Fifth Avenue, New York&limit=1

{
  "status": "ok",
  "results": [
    {"formatted": "350 Fifth Avenue, New York, NY", "lat": 40.7484, "lon": -73.9857, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "es234", "components": {}}
  ]
}

Calculating distance to each store

With the visitor's coordinates in hand, calculate the straight-line distance from that point to each of your store locations, which you keep as a fixed list of coordinates in your own code, using a standard haversine formula.

for store in stores:
    store.distance_km = haversine(store.lat, store.lon, 40.7484, -73.9857)

Showing the result

Sort your store list by the calculated distance and show the closest one, or the closest few, along with the distance figure. Since this all runs server-side on form submission, there is no need for any client-side script, the page simply renders the result on the next page load.

A second example: showing the three nearest instead of one

Rather than reporting only the single nearest store, sorting the full list and showing the top three gives the visitor a genuine choice, particularly useful when the very nearest store might have different hours or stock than a slightly farther one the visitor would actually prefer. This costs nothing extra, since the sort happens against the same coordinates from the same single request.

Handling a low-confidence match

If the visitor's typed address comes back with a low confidence score, show the formatted result back to them for confirmation before running the distance calculation, rather than confidently reporting a distance based on a guess about what they meant.

A common mistake to avoid

Do not run the distance calculation against a query that resolved at a much coarser precision than the visitor probably intended, such as a bare city or region name matching a "locality" type result, without flagging that to the visitor first. A distance calculated from a city center rather than the visitor's actual street can be off by several kilometers in either direction, enough to change which store looks nearest. Checking the precision field before reporting a confident-sounding distance figure avoids presenting a rough estimate as an exact one.

Letting the visitor pick among ambiguous matches

Raising limit above 1 on the geocoding request returns several candidate matches when the typed input is genuinely ambiguous, such as a street name that exists in more than one town. Showing that short list and letting the visitor pick the right one before running the distance calculation is a better outcome than silently committing to whichever candidate happened to rank first.

What it costs

Each calculation is one geocoding request, regardless of how many stores you compare the resulting coordinates against, since the store list itself does not require any further API calls once you have the visitor's coordinates. A landing page with meaningful traffic still uses this feature at a rate of one request per visitor calculation, well inside the 2,500 free requests a day included with every key.

A distance calculator like this answers a specific, common question directly on the page instead of pushing the visitor elsewhere to find out. Full request parameters are on the forward geocoding docs.

Set up a fallback when a lookup returns no result

2026-09-16T19:24:00+00:00

A request that returns successfully with no useful result inside it is easy to mishandle, because it does not look like a failure at the HTTP level, it just does not have the answer you were hoping for.

What an empty result looks like

A forward geocoding search for something too vague or entirely fictional returns a 200 status with an empty results array, not an error code.

GET /v1/forward?q=xyzzy nonexistent place&limit=1

{
  "status": "ok",
  "query": "xyzzy nonexistent place",
  "results": []
}

An IP lookup for an address in an unallocated or private range returns found: false rather than an error, along with whatever fields it can still populate.

{
  "status": "ok",
  "ip": "10.0.0.5",
  "version": 4,
  "found": false
}

Building an explicit fallback path

Check for an empty results array, or found: false, as its own branch in your code, separate from both the success path and the error handling path for 4xx and 5xx responses. Decide deliberately what happens next: ask the user to refine their input, fall back to a broader search with a higher limit, or show a clear "location not found" message rather than a blank space or a misleading default value.

Common causes worth checking for first

A genuinely nonexistent place is one cause, but a poorly formatted input string, a typo, or a query that mixed languages or scripts unexpectedly can also produce an empty result for an address that actually exists. Before assuming the location itself does not exist, consider whether normalizing the input or trying a version with the countries parameter set would resolve it.

Logging empty results separately

Track how often your integration hits an empty result path, separately from your error rate. A rising rate of empty results often points to a data quality problem upstream, in how addresses are being collected or formatted, rather than anything wrong with the lookup itself.

Cost of a no-result lookup

An empty result still costs one request, the same as a successful match, since the lookup was performed either way. There is no separate discounted rate for a lookup that comes back empty.

Treating an empty result as its own deliberate outcome, rather than an afterthought bolted onto error handling, makes an integration noticeably more solid. The errors page covers actual error responses, while empty results are documented alongside each endpoint's normal response shape, such as the forward geocoding docs.

Build a currency-aware pricing page from IP data

2026-09-16T07:55:00+00:00

A price shown in an unfamiliar currency makes a visitor stop and do mental math before they decide anything, which is exactly the moment a pricing page should be at its clearest.

Detecting the visitor's likely currency

Look up the visitor's IP address and read the country_code field, which you can map onto a currency using your own lookup table, the same table you would use if a customer had told you their country directly.

GET /v1/ip?ip=203.0.113.150

{
  "status": "ok",
  "ip": "203.0.113.150",
  "version": 4,
  "found": true,
  "country": "Canada",
  "country_code": "CA",
  "region": "Ontario",
  "city": "Toronto",
  "postcode": "M5H",
  "lat": 43.6511,
  "lon": -79.3808,
  "timezone": "America/Toronto",
  "asn": 4321,
  "org": "Example ISP"
}

Display currency versus settlement currency

Showing a converted price for readability does not require actually charging in that currency. My Geocode's own pricing, for reference, is EUR only worldwide regardless of where a customer signs up from, and that same separation applies to your own pricing page: you can display a localized estimate while still settling every transaction in whatever currency your payment processor actually supports.

Labeling converted prices honestly

If you are showing a converted estimate rather than a price you will actually charge in that currency, label it clearly as an estimate, since exchange rates move and a visitor who expects to be charged exactly the number they saw will be caught off guard if the real charge lands in a different currency at a different rate.

Letting visitors override the detected country

Some visitors are traveling, using a VPN, or simply want to see pricing in a different currency than their detected one. A small currency selector next to the detected default costs nothing extra in requests and avoids trapping anyone in a wrong default.

Request cost

One IP lookup per new visitor session, cached for the visit, is one request. Even a pricing page seeing a lot of daily traffic stays inside the 2,500 free requests a day included with every key, or the same allowance available from a single address without one.

Detecting a likely currency from IP data removes a small but real point of friction on a pricing page, as long as the actual settlement currency is stated clearly. See the IPv4 lookup docs for the field list, and My Geocode's own pricing page for how we handle this ourselves.

Read a confidence score correctly before you trust it

2026-09-15T20:16:00+00:00

A confidence value between 0.0 and 1.0 on a geocoding result looks like a simple pass or fail signal, but treating it that way misses what it is actually measuring.

What confidence measures

Confidence reflects how sure the match is, given the input text, that this particular result is the one the input was referring to. A high confidence score on an ambiguous or oddly formatted input still means the system is confident in its best guess, not that the input was definitely correct or that the location definitely exists as described.

GET /v1/forward?q=Main Street, Springfield&limit=1

{
  "status": "ok",
  "query": "Main Street, Springfield",
  "results": [
    {"formatted": "Main Street, Springfield, IL", "lat": 39.7817, "lon": -89.6501, "type": "address", "precision": "street", "confidence": 0.62, "place_id": "sp901", "components": {}}
  ]
}

A confidence of 0.62 here reflects the fact that many towns share the name Springfield, so even a correct match to one specific Springfield carries some inherent uncertainty about whether it is the Springfield the input meant.

Confidence versus precision

These are two different fields measuring two different things. Precision describes how specific the match is, house, street, or a coarser level. Confidence describes how sure the system is about the match it made. A "house" precision result can still carry a moderate confidence score if the input was ambiguous about which house on which street, and a "street" precision result can carry a high confidence score if the match, though coarse, was unambiguous.

Setting a threshold

Pick a confidence threshold based on what a wrong result would cost you. A threshold of 0.8 or higher makes sense for something automated and consequential, like auto-filling a shipping label with no human review. A lower threshold is reasonable for something with a human checking the result afterward, like a suggestion shown to a customer for confirmation.

Combining with the countries parameter

Ambiguous matches like the Springfield example above are often resolved by narrowing the search with the countries parameter when you already know which country the address should be in, which raises the odds of a high-confidence match on the first try rather than needing a second lookup.

Cost stays the same

Reading confidence correctly does not change what a lookup costs, still one request either way. What it changes is whether you act on the result with the right amount of trust.

Confidence is a specific, narrow signal, not a general correctness guarantee, and reading it that way avoids acting too quickly on a shaky match. Full field definitions are on the forward geocoding docs.

Test your integration without spending your daily quota

2026-09-15T08:23:00+00:00

Building an integration usually means dozens or hundreds of test calls before anything goes near production traffic, and none of that testing needs to touch a paid tier.

Testing with no key at all

2,500 free requests a day are available from any address with no key needed at all, which is enough for most integration work: wiring up request formatting, checking response parsing, and working through error handling for a handful of test cases each.

GET /v1/forward?q=Test Address, Test City&limit=1

No X-API-Key header, no Authorization header, nothing but the request itself.

Watching quota headers while testing

Even without a key, every response carries the same quota headers, so you can watch X-Quota-Used and X-Quota-Free-Remaining climb and fall exactly as they would in production, which is useful for testing how your own code handles those headers before it matters for real.

X-Quota-Limit: 2500
X-Quota-Used: 42
X-Quota-Free-Remaining: 2458

Testing a key without spending credit

Once you sign up and generate a key, that key also gets its own 2,500 free requests a day, separate testing room that does not touch prepaid credit or count against an Unlimited package. This is the point to test key-specific behavior, such as the different ways to send the key, header, bearer token, basic auth, or query parameter, all without spending anything.

Deliberately testing error paths

Send a request with an invalid parameter to see a 400, or an intentionally wrong key to see a 401, so your error handling code has actually been exercised before launch rather than assumed to work. Each of these test calls, successful or not, is one request against the free allowance, not something that should worry you at normal testing volumes.

Moving to production traffic

Once real traffic starts, the same free allowance keeps covering typical daily usage for a lot of smaller integrations, with prepaid credit or an Unlimited package only needed once volume passes 2,500 requests a day.

There is no separate sandbox environment needed here, since the free allowance already gives a full testing ground with the real API. Get started by generating a key from the dashboard, or read the authentication docs first if you want to see the key formats before signing up.

Combine postcode and country for faster lookups

2026-09-14T22:03:00+00:00

Forward geocoding is built to handle messy free text, which means it does work behind the scenes to figure out what kind of input it is looking at. If you already know you have a clean postal code and a country, there is a more direct path.

Going straight to the postcode endpoint

Rather than assembling a free-text string and sending it to /v1/forward, send the code and country directly to /v1/postcode.

GET /v1/postcode?code=90210&country=US

{
  "status": "ok",
  "postcode": "90210",
  "country_code": "US",
  "results": [
    {"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
  ]
}

Why this is the better fit

A postal code and country pair is already fully structured input, so there is no ambiguity for the endpoint to resolve the way there can be with a free-text string that might match multiple similarly worded places. Using the endpoint built for exactly this input shape gets you a cleaner match with less risk of an unexpected result.

A second example: an alphanumeric postal code

The same call works the same way for a country using letters and numbers together rather than digits alone.

GET /v1/postcode?code=K1A 0B1&country=CA

Passing the country parameter is what makes this reliable, since a code string alone is not always unique across countries, and the country parameter is what tells the endpoint which postal system to interpret it against.

When you still need forward geocoding

If you need a specific street-level match rather than the general area a postal code covers, forward geocoding with the full address is still the right tool, since a postal code lookup resolves to the area the code covers, not a specific building within it. Use /v1/postcode for area-level lookups such as validating a shipping zone, and /v1/forward when you need house-level precision.

A common mistake to avoid

Do not assume a postal code always maps to exactly one point that represents every address inside it precisely. The coordinates returned by /v1/postcode represent the code's covered area, which can be a single city block or, in some countries, a much larger zone. Treating that returned point as if it were the exact location of a specific customer's building, rather than a representative point for the whole code, will introduce error into anything distance-sensitive built on top of it.

Combining both in a workflow

A common pattern is validating the postal code and country pair first with /v1/postcode, then, once that passes, sending the full street address to /v1/forward to get exact coordinates. That is two requests per submission, one for each stage, rather than trying to force one endpoint to do both jobs.

An edge case: a code that returns no results

An empty results array means the code was not recognized for the country given, which is a different situation from an error response. Treat it the way you would any other unrecognized input, by asking the customer to re-check what they entered, rather than surfacing it as a system error.

What it costs

Each postcode lookup is one request, the same cost as a forward geocoding lookup. Choosing the right endpoint for structured input does not change what it costs, it changes how directly you get to a correct result.

Reaching for the postcode endpoint when you already have clean, structured input avoids the extra ambiguity that comes with reconstructing a free-text string just to parse it back apart again. Full details are on the postal code lookup docs.

Build a simple IP reputation check for signups

2026-09-14T09:06:00+00:00

A dedicated fraud detection service is more than most small signup forms need. A simple check comparing what an IP address suggests against what a signup form claims catches a reasonable share of obviously mismatched attempts on its own.

GET /v1/ip?ip=198.51.100.200

{
  "status": "ok",
  "ip": "198.51.100.200",
  "version": 4,
  "found": true,
  "country": "Brazil",
  "country_code": "BR",
  "region": "Sao Paulo",
  "city": "Sao Paulo",
  "postcode": "01310",
  "lat": -23.5505,
  "lon": -46.6333,
  "timezone": "America/Sao_Paulo",
  "asn": 8901,
  "org": "Example Cloud Provider"
}

Comparing country against form input

If the signup form asks for a billing country and the value entered does not match country_code from the IP lookup, that alone is not proof of anything wrong, since travel and VPN use are both common and legitimate. Treat a mismatch as one point added to a simple score rather than an automatic rejection.

Weighing network type

The org field often reveals whether an address belongs to a residential ISP or a data center or cloud hosting provider. A signup coming from a cloud hosting network, where a real individual customer would rarely be browsing from, is worth a higher score than one from a recognizable residential ISP, though again not an automatic rejection on its own.

A second example: a small known-ASN list

If you have noticed particular ASN values showing up repeatedly around abusive signups, keeping a short list of those specific asn numbers and adding a fixed score whenever a new signup matches one is a lightweight way to encode that pattern going forward, without needing a full third-party ASN reputation database for a check this modest in scope.

if ip_info["asn"] in known_abuse_asns:
    score += 2

Combining signals into a score

Add up a small number of simple checks: country mismatch, hosting network origin, and anything else specific to your own signup flow, into a single numeric score. Route anything above a threshold you set to manual review or an extra verification step, such as email confirmation, rather than blocking outright.

A common mistake to avoid

Do not score every VPN or hosting-range signup as automatically high risk without any other context. Plenty of legitimate customers browse from a company network that happens to route through a data center IP range, or from a VPN they use for entirely ordinary privacy reasons. Weighting network type as one signal among several, rather than a single disqualifying flag, keeps the check from turning away real customers over a false positive.

An edge case: many signups from one shared address

A shared office network or a large mobile carrier's carrier-grade NAT can put a lot of unrelated, legitimate signups behind the same IP address in a short window. If you are also tracking signup volume per IP as part of your check, set that threshold generously enough to allow for this, or watch it alongside the country and network signals rather than as a rule on its own.

Keeping it proportionate

This kind of check is meant to catch obviously low-effort abuse, not to replace a real fraud prevention system for a business where fraud losses are a serious concern. Treat it as a first filter, not a final verdict.

Request cost

One lookup per signup attempt is one request. Even a form receiving a steady stream of signups stays well inside the 2,500 free requests a day included with every key for typical volumes. The X-Quota-Used and X-Quota-Free-Remaining response headers are a simple way to keep an eye on how much of that allowance a sudden spike in signup attempts is consuming.

A lightweight score built from a couple of IP-derived signals catches more than doing nothing, without the overhead of a dedicated fraud platform. The IPv4 lookup docs list every field available for this kind of check.

Add elevation data to a GPX route file

2026-09-13T20:09:00+00:00

A GPX file recorded from a phone or a basic GPS device often has elevation values that are missing entirely or noticeably inaccurate, since consumer GPS altitude readings are usually far less reliable than the latitude and longitude they record.

Extracting the points

Parse the GPX file's track points, pulling out just the latitude and longitude for each one, and discard the existing elevation values you plan to replace.

<trkpt lat="45.8326" lon="6.8652"><ele>1050</ele></trkpt>

Looking up correct elevation

Send the extracted coordinates to /v1/elevation, either through the points parameter for a smaller file or a bulk POST array for a larger one.

POST /v1/elevation
Content-Type: application/json

[{"lat": 45.8326, "lon": 6.8652}, {"lat": 45.8400, "lon": 6.8700}]

{
  "status": "ok",
  "results": [
    {"lat": 45.8326, "lon": 6.8652, "elevation_m": 1035},
    {"lat": 45.8400, "lon": 6.8700, "elevation_m": 1210}
  ]
}

A second example: checking a single trailhead

Not every use needs a full track processed. Before publishing a hike description, a single call confirms the elevation at the trailhead itself.

GET /v1/elevation?lat=45.8326&lon=6.8652

This returns the same result shape with one entry, useful for spot-checking a starting or ending elevation figure quoted in trail notes without needing to touch the full GPX file.

Writing the values back

Results come back in the same order as the coordinates you sent, so write elevation_m back into each track point's ele tag by matching position, replacing the original recorded value with the looked-up one.

<trkpt lat="45.8326" lon="6.8652"><ele>1035</ele></trkpt>

A common mistake to avoid

Do not mix the points query parameter format and a bulk POST body across a single job without being consistent about how you match results back to track points. The points parameter and the JSON array both return results in the order given, but pulling coordinates for one point via a query parameter and the rest via a bulk POST, then merging the two response sets by assumption rather than by explicit coordinate matching, is an easy way to introduce an off-by-one error into the written-back file.

Deciding how many points to enrich

A GPX file can have thousands of track points recorded at short intervals. Enriching every single one is one request per point, which adds up on a long recorded track. Downsampling to a coarser interval before the elevation lookup, then interpolating between the looked-up values for points in between, is a reasonable way to cut down request count while still producing an accurate looking profile.

An edge case: coastal and low-lying points

A track that dips along a coastline or through a low-lying delta can legitimately return an elevation_m value at or near zero, or occasionally a small negative number for land below sea level. Neither is an error. Treat a value near zero as a plausible real reading for that terrain rather than filtering it out as a bad data point.

What it costs

Each enriched point is one request. A modest hiking track with a few hundred points, sampled down from a much larger raw recording, stays well within the 2,500 free requests a day included with every key.

Cleaning up elevation data this way turns a shaky phone-recorded track into something worth sharing or analyzing. The elevation lookup docs describe both the points parameter and the bulk request format.

Show the right business hours based on visitor location

2026-09-13T08:34:00+00:00

"We're open until 6pm" is only useful if the visitor reading it knows which 6pm you mean. A visitor in a different time zone from your business needs that comparison done in their own local time, not yours.

Getting the visitor's time zone

A single IP lookup returns a timezone field directly, giving you what you need without a separate call.

GET /v1/ip?ip=203.0.113.44

{
  "status": "ok",
  "ip": "203.0.113.44",
  "version": 4,
  "found": true,
  "country": "Japan",
  "country_code": "JP",
  "region": "Tokyo",
  "city": "Tokyo",
  "postcode": "100-0001",
  "lat": 35.6762,
  "lon": 139.6503,
  "timezone": "Asia/Tokyo",
  "asn": 2345,
  "org": "Example Telecom"
}

Comparing against your business hours

Convert your own business hours, stored against your business's own time zone, into the visitor's zone using the timezone identifier you just retrieved, then compare against the visitor's current local time to decide whether to show "open now" or "closed" along with the local time you are showing it as of.

A second example: a business with more than one location

A business with locations in different cities should look up each location's own posted hours against its own stored zone, then compare each separately against the visitor's zone, rather than assuming one set of hours applies everywhere. This matters most when a visitor is comparing two locations on the same page, since one might read as open and the other closed at the exact same moment if they sit in different zones or observe daylight saving differently.

Being explicit about which time zone you mean

Rather than silently converting and hoping the visitor understands, show both pieces clearly, something like "Currently closed. Opens at 9am your time (Asia/Tokyo)." Being explicit avoids confusion when a business operates across a boundary that shifts with daylight saving on one side but not the other.

A common mistake to avoid

Do not compute the open or closed comparison once and cache that boolean result for the rest of the visitor's session. A comparison made at 5:55pm will read "open" and stay wrong by 6:05pm if the underlying open state is cached rather than recalculated. Cache the visitor's time zone identifier, since that is genuinely stable for a session, but recompute the actual open or closed comparison fresh on every render.

An edge case: zones that do not observe daylight saving

Some regions keep a fixed offset year-round while a neighboring region shifts twice a year, which means the gap between two zones is not constant across the calendar. If your comparison logic hard-codes an offset in hours rather than working from the timezone identifier and letting your date library handle the conversion, it will drift out of sync for exactly the weeks around a daylight saving change.

Caching the zone, not the open state

The visitor's time zone identifier is stable for a session and worth caching. Whether the business is currently open changes throughout the day, so recompute that comparison at render time using the cached zone rather than caching the open or closed state itself.

Checking a specific past or future moment

If you need to know what the offset was, or will be, at a specific moment rather than right now, such as confirming what time an order placed yesterday actually was in the customer's zone, /v1/timezone accepts an optional time parameter as a unix timestamp for exactly that kind of historical or future check.

Request cost

One IP lookup per new visitor session covers this feature. That is a single request cached for the length of the visit, keeping a busy storefront site well within the 2,500 free requests a day included with every key.

Getting "open now" right for a global audience is a matter of one lookup and a straightforward time comparison, not a complicated feature. The IPv4 lookup docs list the full response shape.

Handle addresses with no house number

2026-09-12T19:02:00+00:00

Not every address has a house number. Rural routes, some new developments, and well-known landmarks are often referred to without one, and a geocoding request built around expecting a house number every time will misread what a valid result for these looks like.

What the response looks like without one

GET /v1/forward?q=Golden Gate Bridge, San Francisco&limit=1

{
  "status": "ok",
  "query": "Golden Gate Bridge, San Francisco",
  "results": [
    {
      "formatted": "Golden Gate Bridge, San Francisco, CA",
      "lat": 37.8199,
      "lon": -122.4783,
      "type": "address",
      "precision": "street",
      "confidence": 0.9,
      "place_id": "gb567",
      "components": {"city": "San Francisco", "region": "CA", "country": "US"}
    }
  ]
}

Notice there is no house_number field in components here, and precision reads "street" rather than "house". Both of these are expected for an address that genuinely does not have a house number, not signs of a failed or partial lookup.

Reading precision correctly

Treat precision as a description of how specific the match is, not as an error indicator. A "house" precision means the match resolved to a specific building. A "street" precision means it resolved to a street or a point along it, without pinning down an exact building, which is exactly right for a landmark or an address genuinely lacking a house number.

A second example: a well-known public space

GET /v1/forward?q=Central Park, New York&limit=1

A named public space like this typically resolves with type set to something broader than "address" and a precision that reflects an area rather than a single point, along with a components object that may include only a city and region. This is the same pattern as the bridge example: a real, useful result described honestly as covering an area rather than a specific building, because that is what the query actually referred to.

Adjusting validation logic accordingly

If your form validation currently requires a house_number field to be present before accepting an address as complete, that check will incorrectly reject legitimate rural addresses and landmarks. Base acceptance criteria on confidence and precision matching what you actually need, rather than requiring every specific component to be populated.

A common mistake to avoid

Do not treat an empty components object, or one missing several fields, as equivalent to a failed request. A failed request comes back with an error status and an error code, described on the errors docs. A successful result with sparse components is a different, entirely normal outcome, and conflating the two in your error handling will cause valid addresses to be logged and treated as failures.

Letting customers confirm instead of reject

For an address without a house number, showing the formatted result back to the customer for confirmation works better than rejecting the submission outright. This keeps a real address usable while still catching genuinely bad input elsewhere.

The reverse direction has the same pattern

Reverse geocoding a coordinate that sits in open countryside or water can likewise come back with a coarser precision and fewer populated components than a coordinate sitting on a specific building's footprint. The reverse geocoding docs describe the same precision values from that direction.

Cost stays the same

An address without a house number costs the same one request as any other forward geocoding lookup. Nothing about missing components changes how the request is billed against your daily allowance or credit balance.

Handling this correctly is mostly about reading precision and confidence as intended, rather than assuming every valid address must fully populate every component. The forward geocoding docs explain each field in detail.

Geocode addresses in bulk from a CRM export

2026-09-12T07:44:00+00:00

A CRM export is usually a flat file of customer records with an address field and nothing else location-related, no coordinates, no verified components. Turning that into something you can map or segment regionally means geocoding the whole export.

Preparing the export

Pull the address column out of your CRM export as a plain array, keeping the customer ID aligned with each address by position, since you will need to match results back to records afterward.

POST /v1/forward
Content-Type: application/json

["1600 Pennsylvania Avenue, Washington", "221B Baker Street, London"]

{
  "status": "ok",
  "results": [
    {"formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500", "lat": 38.8977, "lon": -77.0365, "type": "address", "precision": "house", "confidence": 0.97, "place_id": "def456", "components": {}},
    {"formatted": "221B Baker Street, London, UK", "lat": 51.5237, "lon": -0.1585, "type": "address", "precision": "house", "confidence": 0.95, "place_id": "abc123", "components": {}}
  ]
}

Writing results back to the CRM

Match each result to its customer by the position you tracked before sending the request, then write the coordinates and components back into your CRM either through its own API or a bulk import, depending on what your CRM supports. Store the confidence and precision fields too, so anything with a weak match can be flagged for cleanup rather than treated as verified.

A second example: an international customer base

A CRM with customers across several countries benefits from passing the countries parameter alongside each region's batch, restricting candidate matches to the expected country and cutting down on the rare case where a street name common in more than one country resolves to the wrong one. Splitting the export into per-country batches before sending each as its own bulk request is a reasonable way to apply this without changing anything else about the workflow.

A common mistake to avoid

Do not deduplicate or reorder the address array before sending it without keeping a separate mapping back to the original customer IDs. Results return in the same order as the array you sent, and once that order is decoupled from your customer records without a saved index, there is no reliable way to match a coordinate pair back to the right customer afterward. Keep the position-to-ID mapping in memory or in a temporary column for the duration of the job.

Re-running on new records only

Once the initial export is geocoded, there is no need to reprocess the whole customer base again later. Track which records already have coordinates and only send new or address-updated records through the endpoint on subsequent runs, keeping ongoing request usage proportional to new activity rather than your total customer count.

Handling records that resolve poorly

A record with a low confidence score or missing several expected components is worth flagging in a review queue rather than writing silently alongside your fully verified records. This keeps a bad address from quietly contaminating a regional report or a map view built from the backfilled data.

What it costs

A one-time backfill of an existing CRM costs one request per customer record with an address, run as a single bulk call or a handful of chunks. A CRM with a few thousand customers might use more than the 2,500 free requests a day in one sitting, which is a reasonable moment to either spread the job across a couple of days or move onto prepaid credit for a one-time push.

Once the backfill is done, ongoing geocoding for new customers is small and steady rather than a recurring bulk job. See the forward geocoding docs for the full request and response shape.

Build a time zone picker that defaults to the visitor's zone

2026-09-11T19:15:00+00:00

Scrolling through a list of time zone names to find your own is a small annoyance that a sensible default removes for almost everyone.

Detecting the zone

The /v1/ip endpoint returns a timezone field directly, so a single call gives you both the location and the time zone identifier together, without a separate call to the timezone endpoint.

GET /v1/ip?ip=203.0.113.88

{
  "status": "ok",
  "ip": "203.0.113.88",
  "version": 4,
  "found": true,
  "country": "Australia",
  "country_code": "AU",
  "region": "New South Wales",
  "city": "Sydney",
  "postcode": "2000",
  "lat": -33.8688,
  "lon": 151.2093,
  "timezone": "Australia/Sydney",
  "asn": 7890,
  "org": "Example Networks"
}

Pre-selecting the picker

Set the timezone value from this response as the selected option in your settings form when it first renders, server-side, before the page reaches the visitor. This works the same whether the picker is a dropdown of standard zone identifiers or a searchable list, since the value you are pre-selecting is just a standard identifier string like the one in the example.

A second example: multiple people on one booking

A travel or event booking form that collects details for more than one traveler benefits from detecting a zone once for the person filling out the form, then applying it as the shared default for every traveler entry rather than looking it up again per traveler. Each traveler field stays editable individually, since a group booking often includes people joining from a different zone than whoever is filling in the form.

Letting the visitor override it

A time zone picker exists specifically because IP-based detection is not always right, particularly for a visitor on a VPN or traveling. Always leave the field editable and save whatever the visitor explicitly picks over the detected default, without re-detecting and overwriting their choice on a later visit.

A common mistake to avoid

Do not assume a large country maps to a single time zone just because your example lookups happen to show one clean identifier. Countries spanning multiple zones will return whichever specific zone matches the visitor's actual location, which is exactly the detail that makes IP-based detection more useful than a country-level guess, but only if your form trusts the specific identifier returned rather than substituting a single default zone for the whole country.

Detect once, not every visit

Run the detection once, the first time a visitor sets up their account or preferences, and store the result. Re-running it on every login would waste requests without adding value, since a visitor's chosen zone, once set deliberately, should stick unless they change it themselves.

If you already have specific coordinates rather than an IP address, such as a delivery address a visitor typed in, /v1/timezone resolves the zone directly from latitude and longitude and can also accept a specific timestamp, which is useful when you need to know the zone as it applied at a particular moment rather than right now.

What it costs

A single lookup per new account or preferences setup is one request. Even a service signing up a steady stream of new users each day stays well inside the 2,500 free requests a day included with every key or available from a single address without one, using this feature alone.

Detecting a sensible default and then getting out of the way is the right balance for a time zone picker. Full field details are on the IPv4 lookup docs and the timezone lookup docs.

Restrict form submissions to a delivery radius

2026-09-11T08:44:00+00:00

A delivery service that only covers a certain area needs a way to reject addresses outside that area before an order gets placed, not after a driver discovers it during dispatch.

Geocoding the submitted address

When a customer submits their delivery address, geocode it before accepting the order.

GET /v1/forward?q=10 Downing Street, London&limit=1

{
  "status": "ok",
  "results": [
    {"formatted": "10 Downing Street, London, UK", "lat": 51.5033, "lon": -0.1276, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "op678", "components": {}}
  ]
}

Comparing against your hub

With the customer's coordinates and your fixed delivery hub coordinates in hand, calculate the straight-line distance between the two using a standard haversine formula in your own code, and compare it against your delivery radius.

distance_km = haversine(hub_lat, hub_lon, 51.5033, -0.1276)
if distance_km > max_radius_km:
    reject_order()

Checking confidence before you reject

A low confidence score on the geocoding result means the address itself was ambiguous, not necessarily that it falls outside your radius. Handle a low-confidence match separately from a clean out-of-radius rejection, perhaps by asking the customer to confirm or refine their address rather than rejecting the order outright.

A second example: choosing the nearest of several hubs

A business running more than one delivery hub should calculate distance to every hub, not just one, and accept the order if any hub's radius covers the address. Assigning the order to whichever hub came back closest also sets up the fulfillment side correctly from the same calculation, since you already have the winning hub's identity once you have sorted by distance.

nearest_hub = min(hubs, key=lambda h: haversine(h.lat, h.lon, cust_lat, cust_lon))
if nearest_hub.distance_km > nearest_hub.max_radius_km:
    reject_order()

A common mistake to avoid

Do not reject an order the instant distance_km exceeds max_radius_km by a trivial amount, such as a few dozen meters, without giving the customer any explanation or recourse. An address sitting essentially on the boundary line is a normal outcome of drawing a radius on a map, and a flat rejection with no context reads as arbitrary to a customer who lives two streets outside a line they cannot see. Showing the calculated distance and the covered radius, rather than a bare rejection, at least explains why.

Using a straight-line radius versus real coverage

A straight-line radius is a simple approximation and will occasionally include a point that is technically far by road, or exclude one that is close by road but far in a straight line, such as across a river with no nearby bridge. For most delivery zone checks this approximation is good enough, and refining it further would require routing data outside what a geocoding lookup provides.

What it costs

Each address check is one geocoding request, or one request per candidate hub compared if you check the address against a hub list through separate calls rather than reusing the same coordinates locally, since only the address itself needs geocoding, not each hub. A delivery form checking every submitted order stays well within the 2,500 free requests a day included with every key for a typical local business, moving onto prepaid credit only once order volume grows substantially.

Rejecting an out-of-area order at submission time, rather than at dispatch, saves both sides a wasted conversation later. Full parameter details are on the forward geocoding docs, and current pricing tiers are on the pricing page.

Add a "detect my location" button without the browser prompt

2026-09-10T20:25:00+00:00

The browser's built-in location prompt asks for GPS-level precision and requires an explicit permission click, which a lot of visitors decline on reflex. A "detect my location" button does not have to go through that dialog at all if approximate location is good enough for what you are building.

Detecting from the server side

When the button is clicked, submit a request to your own server, which already sees the visitor's IP address on the connection. Look that address up against /v1/ip and use the result directly, with no browser permission dialog involved at any point.

GET /v1/ip

{
  "status": "ok",
  "ip": "198.51.100.23",
  "version": 4,
  "found": true,
  "country": "Italy",
  "country_code": "IT",
  "region": "Lombardy",
  "city": "Milan",
  "postcode": "20121",
  "lat": 45.4642,
  "lon": 9.1900,
  "timezone": "Europe/Rome",
  "asn": 3456,
  "org": "Example ISP"
}

Calling the endpoint with no ip parameter, as shown here, looks up whichever address made the request, which is exactly the visitor's own address when your backend calls it on their behalf.

Setting expectations correctly

IP-based location is city-level at best, not GPS precision. Label the feature honestly, something like "detect my approximate area" rather than implying pinpoint accuracy, so a visitor is not surprised when the result is a city center rather than their exact street.

A second example: regional pricing display

The same button pattern works for showing region-appropriate pricing or currency context on a landing page. Since every price is quoted in EUR regardless of visitor location, a button like this would be used to prefill a shipping estimate or a regional contact number rather than to change the currency shown, but the underlying request is identical, one IP lookup returning enough to fill in city and country immediately.

Where this fits well

This approach fits store locators, regional content defaults, and shipping estimates, where a city or region is all that is needed. It does not replace GPS location for something like turn-by-turn navigation, where the browser prompt and real device location are genuinely necessary.

A common mistake to avoid

Do not treat a corporate network or VPN connection as a special error case that needs handling differently from any other lookup. The endpoint will still return a result, just one centered on wherever that network's registered address happens to be, which can be a different city or even a different country from where the visitor is actually sitting. The right response is the same one you would give for any IP-based estimate: let the visitor override it, rather than trying to detect and specifically flag VPN traffic as unusual.

Falling back gracefully

If found comes back false, which can happen for some address ranges, fall back to asking the visitor to type a location manually rather than showing an error, since the whole point of the button was to save that step, not to introduce a dead end.

Cost of the feature

Each click is one request. A button used occasionally by visitors stays a tiny fraction of the 2,500 free requests a day included with every key or available from a single address without one. Both IPv4 and IPv6 visitors resolve through the same call, so there is no separate code path needed for either version.

Skipping the permission dialog trades precision for convenience, which is the right trade for a lot of location features. The IPv4 lookup docs cover the endpoint's full response.

Parse a free-text address field into structured components

2026-09-10T07:58:00+00:00

A single free-text address field is easy to collect and hard to work with afterward, especially once you need to filter by city or group by region. Forward geocoding does the parsing for you as a side effect of resolving the address to coordinates.

Sending the free text

GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1

{
  "status": "ok",
  "query": "1600 Pennsylvania Avenue, Washington, DC 20500",
  "results": [
    {
      "formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
      "lat": 38.8977,
      "lon": -77.0365,
      "type": "address",
      "precision": "house",
      "confidence": 0.97,
      "place_id": "def456",
      "components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
    }
  ]
}

Storing components separately

Once you have the components object, write each field into its own database column rather than keeping only the original free-text string. This makes it possible to filter customer records by city or region, generate accurate regional reports, and validate that a postal code and city actually belong together, none of which is practical against a single unstructured string.

A second example: an address in a different format

Address structure is not the same everywhere. A United Kingdom address might resolve with a county in place of a US-style region, and a component like house_number might be entirely absent for a named building. Sending the same style of request works regardless of country, but the component keys you actually get back can vary, so build your storage schema to tolerate a component being missing rather than assuming every country fills in the exact same set every time.

A common mistake to avoid

Do not hard-code an assumption that every result will contain all of house_number, street, city, region, and postcode, then treat any address missing one of them as a parsing error. A perfectly valid address, especially outside a house-numbered urban grid, can legitimately come back with some fields empty. Building strict validation around a full set of components will reject real customer input that the endpoint parsed correctly.

Keeping the original text too

Store the original free-text input alongside the parsed components rather than discarding it. If a component comes back incomplete or a customer needs to correct something later, having the original text on hand makes re-parsing or manual correction straightforward.

Handling partial parses

Not every address resolves with every component filled in. A rural address might come back without a house_number, and a small town might come back without a distinct region value. Treat missing component fields as legitimately empty rather than as a parsing failure, and fall back to the formatted string for display when a specific component you wanted is not present.

Handling more than one plausible match

Raising limit above 1 returns several candidate results ordered by how well each matches the free text, which is useful when you want to show the customer a short pick list rather than silently committing to the top match. This is a reasonable middle ground between full automatic parsing and a fully manual entry form, particularly for addresses your confidence threshold would otherwise flag as uncertain.

What it costs

Parsing a free-text field this way costs one request per address, the same as any other forward geocoding lookup. A backfill job cleaning up an existing table of free-text addresses can run through the whole table as a bulk request, one request per row.

Turning free text into structured fields is a natural side effect of geocoding an address, not an extra step. The forward geocoding docs list every component the endpoint can return.

Set up polling for a large batch job without a webhook

2026-09-09T22:23:00+00:00

Some APIs hand back a job ID for a large batch and expect you to poll or wait for a webhook while it processes in the background. This one does not work that way. Every bulk request, large or small, is answered synchronously in the same call, which changes how you should think about running a very large job.

Chunking instead of queuing

Rather than submitting one enormous array and waiting, split a large job into fixed-size chunks, a few hundred to a few thousand items each, and send them as a sequence of ordinary bulk POST requests. Since each call returns its results immediately, there is no job status to poll for, only the next chunk to send.

POST /v1/forward
Content-Type: application/json

["address 1", "address 2", "... up to a few hundred items"]

What "polling" actually means here

The closest thing to polling in this setup is checking your own quota headers between chunks rather than checking a job status. Read X-Quota-Free-Remaining and X-Credits-Remaining after each chunk completes, and pause the job, or stop it, if you are about to run past your daily free allowance without enough prepaid credit to continue.

X-Quota-Free-Remaining: 340
X-Credits-Remaining: 12.50

Building a simple runner

A small script that loops over chunks, sends each one, checks the headers on the response, and either continues or pauses based on what it sees is all a large batch job needs here. There is no separate job status endpoint to call, since the chunk you just sent already contains everything you asked for.

Resuming after a pause

Track which chunk index you have successfully processed so far, so a pause for a quota reset or a credit top-up can resume exactly where it left off rather than reprocessing earlier chunks and spending requests twice.

What it costs

Cost is the same either way, one request per item across the whole job. The chunking approach only changes how you manage the job, not how many requests it uses in total.

Treating a large job as a sequence of ordinary synchronous chunks, rather than looking for an async job system that does not exist here, keeps the whole thing simple. The rate limits docs cover the quota headers that drive this pattern.

Calculate distance between two geocoded points

2026-09-09T08:56:00+00:00

Distance between two addresses is not something a geocoding API returns directly, since a distance calculation only needs coordinates, which the forward endpoint already gives you for any address you send it.

Getting coordinates for both addresses

Geocode each address separately, or together in a single bulk request, to get a latitude and longitude pair for each.

POST /v1/forward
Content-Type: application/json

["221B Baker Street, London", "10 Downing Street, London"]

{
  "status": "ok",
  "results": [
    {"formatted": "221B Baker Street, London, UK", "lat": 51.5237, "lon": -0.1585, "type": "address", "precision": "house", "confidence": 0.95, "place_id": "abc123", "components": {}},
    {"formatted": "10 Downing Street, London, UK", "lat": 51.5033, "lon": -0.1276, "type": "address", "precision": "house", "confidence": 0.96, "place_id": "op678", "components": {}}
  ]
}

Calculating the distance

With two coordinate pairs in hand, apply the standard haversine formula, which converts the difference in latitude and longitude into a straight-line distance across the Earth's surface. Most programming languages have a small, well-tested haversine implementation available as a short function or a common library, so there is no need to write the trigonometry from scratch.

distance_km = haversine(51.5237, -0.1585, 51.5033, -0.1276)

A common mistake to avoid

The haversine formula expects latitude and longitude in radians, but the coordinates in an API response are always in degrees. Plugging degree values straight into a formula written for radians will produce a distance that looks plausible at a glance but is quietly wrong by a large factor. Convert degrees to radians first, or use a library function that documents which unit it expects, and check the result against a distance you already know before trusting it in production.

A second example: total length of a multi-stop route

The same calculation extends naturally to more than two points. Geocode every stop on a route in one bulk request, then sum the haversine distance between each consecutive pair of coordinates to get a rough total route length, useful for a quick delivery route estimate even before you have real turn-by-turn routing in place.

total_km = haversine(a, b) + haversine(b, c) + haversine(c, d)

Straight-line versus travel distance

A haversine calculation gives straight-line distance, not driving or walking distance along real roads. For most uses, such as sorting nearby locations or estimating rough proximity, straight-line distance is good enough and needs nothing beyond the coordinates you already have. If you specifically need routed travel distance, that is a separate kind of calculation outside what a geocoding lookup provides.

An edge case worth knowing

Two points on opposite sides of the antimeridian, or very close to a pole, can trip up a naive distance formula that does not account for longitude wrapping around from 180 to negative 180. This is rare for typical address-to-address distance checks, but worth testing for if your application legitimately spans that part of the globe.

Request cost

Geocoding two addresses costs two requests, whether sent as separate calls or one bulk call. The distance math itself, once you have both coordinate pairs, happens entirely in your own code and costs nothing further against your allowance.

Reusing coordinates you already have

If either address is one you have geocoded before and cached, only the new address needs a fresh request, cutting the cost for that particular calculation to one request instead of two.

Distance calculations are one geocoding request away for any address you have not already resolved to coordinates. See the forward geocoding docs for the full response shape.

Build a store locator with reverse geocoding

2026-09-08T21:50:00+00:00

A store locator needs two things working together: a way to know where the customer is, and a list of store coordinates to compare against. Reverse geocoding covers the first part cleanly.

Turning coordinates into a readable location

Once you have the customer's coordinates, from a location they entered or from an IP lookup, reverse geocode them to show a readable place name back to the customer, confirming the search location before showing results.

GET /v1/reverse?lat=51.5074&lon=-0.1278

{
  "status": "ok",
  "formatted": "Trafalgar Square, London, UK",
  "lat": 51.5074,
  "lon": -0.1278,
  "type": "address",
  "precision": "street",
  "confidence": 0.9,
  "place_id": "lm345",
  "components": {"city": "London", "country": "GB"}
}

Finding the nearest stores

The API returns coordinates, not distances between two arbitrary points, so once you have the customer's latitude and longitude, calculate distance to each store in your own list using standard great-circle distance math on the two coordinate pairs. Sort your store list by that calculated distance and show the closest few.

Letting customers type an address instead

Not every visitor will share their location. For a typed address search, geocode the entered text with /v1/forward first to get coordinates, then run the same nearest-store distance calculation against that result. If you want suggestions to appear as the customer types rather than waiting for a full address, /v1/autocomplete can back a type-ahead field that feeds a place_id or resolved text into the same forward geocoding step.

A second example: a mobile app using device GPS

A native app can skip the reverse geocoding step for finding nearby stores, since it already has raw device coordinates to compare against your store list directly. Reverse geocoding still earns its place there for the confirmation text shown to the customer, something like "Showing stores near Trafalgar Square, London" rather than a bare pair of numbers, which reassures the customer that the app understood their location correctly before they scroll through results.

A common mistake to avoid

Do not assume every typed address geocodes to house-level precision before running the distance calculation. A broad query like just a city name will still return a result, but at a coarser precision, and treating that coarse point as if it pinpointed the customer's exact building will make your "nearest store" ranking less reliable than the confidence and precision fields would have told you to expect.

Handling a tie between two nearby stores

When two stores come back at nearly identical calculated distances, distance alone will not tell the customer which one actually suits them better. Showing both, along with details like opening hours or stock availability, gives the customer the deciding factor rather than an arbitrary sort order.

Confirming the match

Show the formatted address from the reverse geocoding result alongside the store results, so the customer can immediately see whether the location that was detected or resolved matches where they actually meant to search from, and can correct it if not.

What it costs

Each search is one reverse or forward geocoding request, regardless of how many stores you compare it against afterward, since the distance calculation itself happens in your own code once you have coordinates for both sides. A store locator getting a moderate amount of daily traffic fits easily within the 2,500 free requests a day included with every key.

A store locator built this way needs exactly one geocoding request per customer search, with everything after that handled locally against your own store list. Full response fields are on the reverse geocoding docs.

Add a country dropdown that defaults from IP

2026-09-08T08:48:00+00:00

A country dropdown that defaults to whatever a visitor's IP address suggests saves most people a scroll through a long list, as long as it still lets them change it when the default is wrong.

Getting the default value

Look up the visitor's IP address on your server when the page is requested, and read the country_code field from the response to set as the dropdown's selected option before the page is even sent to the browser.

GET /v1/ip?ip=192.0.2.15

{
  "status": "ok",
  "ip": "192.0.2.15",
  "version": 4,
  "found": true,
  "country": "Spain",
  "country_code": "ES",
  "region": "Madrid",
  "city": "Madrid",
  "postcode": "28001",
  "lat": 40.4168,
  "lon": -3.7038,
  "timezone": "Europe/Madrid",
  "asn": 5678,
  "org": "Example Networks"
}

Rendering it server-side

Since this happens entirely server-side, before rendering the page, there is no flash of a wrong default followed by a correction in the browser, which is what happens with client-side approaches that call out after the page has already loaded. Set the selected attribute on the matching option directly in the HTML you generate, matching country_code against whatever ISO codes your option values already use.

A second example: prefilling a checkout country field

The same call works just as well on a checkout page as on a signup form. Look up the shopper's IP once when the checkout page loads, match country_code to your shipping country list, and select it by default. Because the shipping country affects tax and delivery options shown further down the page, getting this right before the page renders avoids a jarring reflow later if the visitor had to correct it after everything else had already loaded around a wrong default.

Always allow a change

Treat the IP-based country as a starting point, not a locked-in answer. A visitor traveling, using a work VPN, or simply living somewhere their network provider's registered address does not match will need to pick a different option, so nothing about the form should assume the default is correct.

A common mistake to avoid

Do not cache the fully rendered page behind a CDN or reverse proxy without varying it by visitor, since a page rendered once for the first visitor's IP and then served from cache to everyone afterward will show that first visitor's country to every subsequent visitor regardless of where they actually are. If your pages are cached at all, either exclude this fragment from the cache or render it through a small server-side include that runs per request.

Handling a lookup that finds nothing

If found comes back false, which happens for some private or unallocated ranges, fall back to a neutral default, such as an empty selection or your most common country, rather than leaving the field in an undefined state.

IPv6 visitors work the same way

A visitor connecting over IPv6 gets the same country_code field back from the same endpoint, just resolved against a /48 network rather than a /24. Nothing about the dropdown logic needs to change based on which IP version made the request. See the IPv6 lookup docs if you want the version-specific details.

Cost of this feature

This is one request per new visitor session, cached for the session so a single visit does not trigger repeated lookups across multiple form pages. That keeps the feature well within the 2,500 free requests a day included with every key, or available from a single address without one, for any but the busiest sites.

A sensible default saves a scroll through a hundred-item list, and the visitor still has full control if it guesses wrong. Field details are on the IPv4 lookup docs.

Filter bot traffic using ASN and network data

2026-09-07T19:43:00+00:00

Most real visitors connect from residential or mobile networks. Most automated traffic connects from data centers and cloud hosting providers. That difference shows up plainly in the asn and org fields on an IP lookup.

Getting network data

GET /v1/ip?ip=203.0.113.99

{
  "status": "ok",
  "ip": "203.0.113.99",
  "version": 4,
  "found": true,
  "country": "United States",
  "country_code": "US",
  "region": "Virginia",
  "city": "Ashburn",
  "postcode": "20147",
  "lat": 39.0438,
  "lon": -77.4874,
  "timezone": "America/New_York",
  "asn": 16509,
  "org": "Example Cloud Hosting"
}

Building a simple filter

Maintain a short list of organization name patterns or specific ASN numbers you associate with cloud hosting and known automation platforms, based on your own traffic history, and flag traffic from those networks for extra scrutiny, such as a CAPTCHA challenge or a lower trust score, rather than blocking outright. Legitimate uses of cloud IP ranges exist, including corporate VPNs and mobile carrier infrastructure, so this signal works best combined with behavioral signals rather than used alone.

A second signal: country mismatch

Combining the ASN check with the country_code field catches a different pattern. An account that claims to be based in one country but consistently signs in from a data center address registered in another is a stronger signal together than either fact is alone. Neither field on its own proves anything, since real customers travel and use VPNs for entirely ordinary reasons, but the combination is worth weighting more heavily in a scoring system than either check run in isolation.

Where this fits in a request

Run the ASN check at the point traffic first hits your application, such as a signup form or a login attempt, rather than after the fact, so the signal can actually influence what happens next. Cache the result for the length of a session, since an address's ASN does not change mid-session.

Handling returning visitors

A visitor who was scored once during signup and returns later from the same network address does not need a fresh lookup every time, since the asn and org fields for a given address remain stable across sessions. Cache the classification against the address itself, not just the session, so a known-safe residential address is not re-evaluated on every single future visit either.

A mistake worth avoiding

Blocking every request from a recognized hosting or cloud ASN outright, rather than scoring it, shuts out a real slice of legitimate traffic along with the automated traffic you actually meant to stop. Corporate VPN exits, some mobile carriers, and privacy-focused browsers all route through infrastructure that can register the same way a hosting provider does. Use the ASN and org fields as one input into a scoring or challenge decision, not as an automatic block rule on their own.

What it costs

One lookup per new session, cached afterward, is one request per visitor rather than one per request they make. On a site processing meaningful signup or login volume, this stays inside the 2,500 free requests a day included with every key for moderate traffic, and moves onto prepaid credit or an Unlimited key once volume grows past that.

Network origin is one signal among several, not a verdict on its own, but it is a cheap one to add to a signup or login flow. The IPv4 lookup docs and IPv6 lookup docs describe every field the endpoint returns.

Batch resolve postal codes for a customer list

2026-09-07T08:13:00+00:00

A customer export with a postal code column but no coordinates is a common starting point for anything involving shipping zones, regional reporting, or store assignment. Resolving the whole column at once is faster than writing a loop.

Sending the batch

POST an array of code and country objects to /v1/postcode. Each item resolves independently and comes back in the same order.

POST /v1/postcode
Content-Type: application/json

[{"code": "10115", "country": "DE"}, {"code": "75001", "country": "FR"}]

{
  "status": "ok",
  "results": [
    {"postcode": "10115", "country_code": "DE", "results": [{"lat": 52.5300, "lon": 13.3800, "components": {"city": "Berlin", "region": "Berlin"}}]},
    {"postcode": "75001", "country_code": "FR", "results": [{"lat": 48.8630, "lon": 2.3360, "components": {"city": "Paris", "region": "Ile-de-France"}}]}
  ]
}

Matching results back to customer records

Keep the original row index or customer ID alongside each code and country pair before sending the request, and match results back onto customer records by that same position, the same approach that works for bulk forward or reverse geocoding.

Deduplicating before you send

A customer list of any real size tends to have far fewer distinct postal codes than it has rows, since many customers share the same code in any given city or neighborhood. Build a unique list of code and country pairs first, resolve that smaller list in one batch, and then map the results back onto every customer row that shares each code, rather than sending one array entry per customer and paying for the same code and country pair over and over.

Handling codes that do not resolve

An empty results array for a particular item usually means the code and country pair does not exist, which is common in an old export with typos or an outdated postal code. Flag those rows for manual review rather than silently dropping them from your report.

An edge case: formatting differences

A code stored as "SW1A1AA" without a space and one stored as "SW1A 1AA" with one may or may not resolve the same way depending on how consistently your own export formats codes, so normalizing spacing and case in your export before building the batch array reduces the number of rows that fail to resolve purely on formatting rather than on the code being genuinely wrong.

What it costs

A batch is billed one request per item, so a 2,000 row customer list costs 2,000 requests, whether sent as one bulk call or as 2,000 separate ones. Sending it as one call is still worth doing for the reduced overhead and the single set of quota headers to check, even though the request count against your allowance is identical either way. Deduplicating first, as above, is what actually reduces the request count, not the choice between bulk and individual calls.

Watching your allowance mid batch

For a list large enough to run past the free 2,500 requests a day, check X-Quota-Free-Remaining before you commit to running the whole thing in one sitting, or split it across a couple of days if you are not planning to move onto prepaid credit for a one-off job.

Resolving a whole customer list's postal codes in a single call turns what used to be a slow background job into one straightforward request. The postal code lookup docs cover the full field list.