BigDataCloud React Native Client

Official React Native client for BigDataCloud free APIs — reverse geocoding and roaming detection.

No API key required. Works with Expo and bare React Native.

Installation

npm install @bigdatacloudapi/react-native-client

With Expo (recommended):

npx expo install expo-location

Bare React Native:

npm install @react-native-community/geolocation

Permissions

Expo (app.json)

{
  "expo": {
    "plugins": [
      ["expo-location", {
        "locationWhenInUsePermission": "Used to show your current city and country."
      }]
    ]
  }
}

Bare React Native (AndroidManifest.xml)

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS (Info.plist)

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show your current city and country.</string>

Quick Start

import { useReverseGeocode } from '@bigdatacloudapi/react-native-client';

export default function MyScreen() {
  const { data, loading, accuracy } = useReverseGeocode();

  if (loading) return <ActivityIndicator />;

  // Always show the accuracy level — never silently present IP-based as GPS
  const label = {
    FINE:     'GPS location',
    COARSE:   'Approximate location',
    IP_BASED: 'IP-based — enable location for better accuracy',
  }[accuracy ?? 'IP_BASED'];

  return (
    <View>
      <Text>{data?.response.city}, {data?.response.countryName}</Text>
      <Text>{label}</Text>
    </View>
  );
}

Location Strategy

1. FINE (GPS) — expo-location with Accuracy.High (or RN Geolocation with enableHighAccuracy: true). Always requested first.
2. COARSE (network/wifi) — returned automatically when GPS accuracy is reduced.
3. IP_BASED — no coordinates available. Server uses caller's IP. Only when all location is denied.

Always surface the accuracy value to your users. Never silently present IP_BASED results as GPS.

Roaming Detection

import { useAmIRoaming } from '@bigdatacloudapi/react-native-client';

export default function RoamingScreen() {
  const { data, loading } = useAmIRoaming();

  if (loading) return <ActivityIndicator />;

  return (
    <Text>
      {data?.isRoaming
        ? `Roaming in ${data.roamingCountryName}`
        : 'Not roaming'}
    </Text>
  );
}

API

useReverseGeocode(localityLanguage?)

Return	Type	Description
data	GeocodeResult | null	Response + accuracy level
loading	boolean	True while fetching
error	Error | null	Any error that occurred
accuracy	AccuracyLevel | null	'FINE', 'COARSE', or 'IP_BASED'
refresh	() => void	Re-trigger detection

useAmIRoaming()

Return	Type	Description
data	RoamingResponse | null	Roaming status
loading	boolean	True while fetching
error	Error | null	Any error
refresh	() => void	Re-trigger

Fair Use Policy

This library uses BigDataCloud's free client-side reverse geocoding API (api.bigdatacloud.net), governed by the Fair Use Policy.

This API is for resolving the current, real-time location of the calling device only.

Key rules:

• Client-side only — requests must originate directly from the device being located, not from a server or automated script
• Real-time coordinates only — only live GPS/WiFi coordinates obtained at the moment of the call are permitted. Pre-stored, cached, or externally-sourced coordinates are strictly not allowed
• User consent required — coordinates must be obtained via platform geolocation APIs with the user's explicit permission

Violations result in a 402 error and your IP address being banned.

If you need to geocode coordinates you already have, or need server-side geocoding, use the Reverse Geocoding API with a free API key instead — it includes 50,000 free queries per month.

License

MIT — see LICENSE.