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.