New Feature Update Free Client Side Reverse Geocoding Api with Ip Geolocation Fallback

A privacy-first way to localise digital experiences: resolve a user’s locality in the browser, and automatically fall back to IP geolocation when permission isn’t granted — all via a single endpoint that returns the same structured response.

The problem

Location is fundamental to many online experiences — from tailoring content, pricing and language, to improving analytics, payment risk checks and fraud controls. The straightforward way to obtain location is through browser HTML5 geolocation or mobile services, which can return precise latitude and longitude. However, that approach surfaces several practical challenges:

Privacy concerns. Exact coordinates are sensitive. Many users are uncomfortable sharing them, and some organisations prefer not to collect or store precise location data at all.
Permission dependency. If a user denies the location prompt, or if the device cannot provide a fix, your application may lose all location context.
Over-collection. In a large proportion of use cases you only need a locality (for example, Adelaide, South Australia) rather than pinpoint accuracy. Requesting lat/lon can therefore be excessive.
Inconsistent outputs. Combining GPS-based reverse geocoding and IP-based estimation often produces different schemas, naming conventions and field depths, complicating downstream logic and reporting.
Operational risks. Client-side use of premium services can expose API keys, rate limits and costs, particularly if you need a fallback path.

The result is a brittle implementation: you might either over-collect data (hurting trust) or lack a usable fallback (hurting UX and conversion).

The solution

BigDataCloud’s Free Reverse Geocode to City API addresses these trade-offs with a client-first design and an automatic IP fallback — using the same endpoint in both cases.

Client-side reverse geocoding when permitted. If the user grants access, the browser retrieves lat/lon and resolves them to a textual locality on the client. Your systems can use the locality without ever handling raw coordinates.
IP geolocation when permission isn’t granted (or is unavailable). Call the same endpoint without coordinates and it automatically estimates location from IP.
Consistent JSON output in all cases. You receive a stable schema with a clear indicator (lookupSource) showing whether the result came from reverseGeocoding or ipGeolocation.
No API key required for the free client endpoint. Ideal for public websites, trials and rapid prototypes.

Illustration of the client-side reverse geocoding flow with automatic IP fallback. The user may grant or deny permission; both paths call the same endpoint and return the same structured response. — Supporting diagram: the location prompt may be granted or denied. In both cases you call the same endpoint and receive the same structured response with `lookupSource` indicating the method used.

How it works

Prompt the user for location access. The browser displays a permission dialogue.
If granted, the device provides latitude and longitude. Call the endpoint with those coordinates to perform client-side reverse geocoding.
If denied or unavailable, call the same endpoint without coordinates; it automatically falls back to IP geolocation.
Receive a consistent JSON response either way. Downstream code doesn’t need to branch by schema — only by the value of lookupSource if you wish to label precision in the UI.

Endpoint & response structure

See the full endpoint description on the product page: Reverse Geocode to City (Free API). Typical request patterns:

With coordinates: include latitude, longitude, and (optionally) localityLanguage.
Without coordinates: omit latitude/longitude; the service will estimate from IP.

Common response fields (subset; field names may evolve — consult the documentation for the latest list):

countryName, countryCode
principalSubdivision, principalSubdivisionCode
city and/or locality, postcode
localityInfo (hierarchical context)
lookupSource — either reverseGeocoding or ipGeolocation

The consistent shape makes it straightforward to log, store and analyse results across both permission states.

Implementation guidance

UX & consent

Ask for location at a moment of clear benefit (e.g., “Show nearby stores”). This improves consent rates.
Explain that you only need locality, not precise coordinates, which helps build trust.
Offer a graceful “Not now” path — your fallback will still provide useful context.

Backend & analytics

Store the returned locality fields as your source of truth; avoid persisting raw coordinates unless absolutely necessary.
Record lookupSource to understand what proportion of traffic is GPS-derived versus IP-derived.
Use short-lived caching to reduce repeats within a session. If your UI is server-rendered, cache at the edge to minimise latency.

Error handling

If geolocation times out, skip retries that block the interface; proceed with the no-coords request immediately.
Display neutral copy such as “Approximate location detected” when the fallback is used.

Language handling

Set localityLanguage to obtain labels in your preferred language. Default to English (en) if unsure.

Security & privacy

Prefer the client-side-only flow for locale targeting and content personalisation; this avoids transmitting sensitive lat/lon to your servers.
When you do handle coordinates, treat them as sensitive and minimise retention.

Which path should I prefer?

Use client-side reverse geocoding whenever permission is granted and you need the most reliable locality for a given user session. The IP fallback remains valuable for first-time visitors, privacy-conscious audiences, corporate networks, and devices without GPS.

Because the response is consistent, you can implement once and handle both outcomes with a single code path.

Frequently asked questions

Do I need an API key?

No — the free client endpoint does not require an API key.

Is IP geolocation accurate enough?

It’s generally suitable for coarse-grained localisation (for example, country, state and city). Precision can vary for VPNs, proxies, hosted environments and mobile networks. If your use case requires pinpoint accuracy or address-level data, always rely on the permission-granted path.

What happens if the user changes their decision?

If the user later grants permission, start including coordinates; your integration doesn’t change, and you’ll continue receiving the same field set.

Where can I find parameters and field descriptions?

Refer to the product documentation: Reverse Geocode to City (Free API).

Try it now

Implement a single, privacy-aware flow that works whether users grant permission or not. Explore the Free Reverse Geocode to City API and integrate it into your site today.

New Feature Update: Free client-side reverse geocoding API with IP geolocation fallback