Free Location Detection in React — One Hook, Zero Configuration

Adding location awareness to a React app usually means signing up for a geocoding service, managing API keys, and writing fallback logic for when GPS is unavailable. What if you could skip all of that?

We've just released @bigdatacloudapi/react-reverse-geocode-client — a React hook that detects your user's city, country, and locality with zero configuration. No API key, no account, no billing setup.

30-Second Setup

npm install @bigdatacloudapi/react-reverse-geocode-client

import { useGeoLocation } from '@bigdatacloudapi/react-reverse-geocode-client';

function App() {
 const { data, loading, error, source } = useGeoLocation();

 if (loading) return <p>Detecting location...</p>;
 if (error) return <p>Error: {error}</p>;

 return (
 <div>
 <h1>📍 {data?.city}, {data?.countryName}</h1>
 <p>Region: {data?.principalSubdivision}</p>
 <p>Detected via: {source}</p>
 </div>
 );
}

That's the entire integration. Your app now has location detection.

How It Works

The useGeoLocation() hook implements a two-tier detection strategy:

1. GPS first — requests the browser's geolocation API (the user sees a standard permission prompt). If granted, precise coordinates are sent to BigDataCloud's free reverse geocoding API which converts them to structured location data.
2. Automatic IP fallback — if GPS is denied, unavailable, or times out, the same endpoint is called without coordinates and automatically resolves the user's location from their IP address using BigDataCloud's patented IP geolocation technology.

Critically, both paths return the identical JSON structure. Your UI code doesn't need to handle two different response formats — it just works regardless of how the location was determined.

The Response

The hook returns rich, structured location data including:

• Country — name, ISO code, continent
• Region — state/province with ISO 3166-2 code
• City and locality (neighbourhood/suburb)
• Postcode
• Administrative hierarchy — from country down to neighbourhood level
• Lookup source — tells you whether GPS or IP was used

All locality names are available in 100+ languages via the language option — a feature not available in most geocoding services, even paid ones.

Configuration Options

// Multi-language — get names in Japanese
const { data } = useGeoLocation({ language: 'ja' });
// data.countryName → "日本", data.city → "東京"

// Manual trigger — detect on button click, not on mount
const { data, refresh } = useGeoLocation({ manual: true });
<button onClick={refresh}>Detect My Location</button>

Works with Next.js and SSR Frameworks

The hook checks for navigator before accessing geolocation, so it's safe in server-side rendering environments. For Next.js, use it in client components:

'use client';
import { useGeoLocation } from '@bigdatacloudapi/react-reverse-geocode-client';

Non-React Usage

The package also exports a standalone reverseGeocode() function for use outside React components:

import { reverseGeocode } from '@bigdatacloudapi/react-reverse-geocode-client';

// With coordinates
const data = await reverseGeocode({ latitude: 48.8566, longitude: 2.3522 });
console.log(data.city); // "Paris"

// IP fallback
const data = await reverseGeocode();
console.log(data.countryName); // detected from IP

Why No API Key?

There's no hidden catch. When the hook sends GPS coordinates to our endpoint, the browser also reveals its IP address. This anonymous pairing of "GPS position + observed IP" helps us continuously validate and improve our IP geolocation accuracy — which we benchmark daily in our public accuracy report. No personal data is logged or tracked. You provide location context, we provide the geocoding service. Fair exchange.

Fair Use and Development

The free client-side API is for production client-side use only — calls from the user's browser or mobile app. During development and testing (where you might call from localhost, emulators, or API tools), use our server-side reverse geocoding API instead. It provides the same data and includes 50,000 free queries per month with a free API key. See our fair use policy for details.

AI-Friendly Prompts

Building with an AI coding assistant? Try these prompts:

• "Add location detection to my React app using @bigdatacloudapi/react-reverse-geocode-client. Show city and country with a loading state."
• "Create a React component that detects the user's location in Japanese and shows it on a card."
• "Build a Next.js page that shows the user's city, region, and postcode using BigDataCloud's free useGeoLocation hook."

Get Started

• npm: npm install @bigdatacloudapi/react-reverse-geocode-client
• GitHub: github.com/bigdatacloudapi/react-reverse-geocode-client
• API docs: Free Client-Side Reverse Geocoding API

One hook. Zero configuration. Location awareness for every React app.