react-native-nitro-geocoder

A high-performance native geocoding library for React Native using Nitro Modules JSI bindings.

Features

• JSI-powered: Direct native calls without async bridge overhead
• Forward Geocoding: Convert addresses to coordinates
• Reverse Geocoding: Convert coordinates to addresses
• Multiple Results: Get multiple geocoding suggestions
• Locale Support: Configurable language for results
• Distance Calculation: Native distance calculation (synchronous)
• Zero Dependencies: Uses native platform APIs only
  • iOS: CLGeocoder (CoreLocation)
  • Android: android.location.Geocoder

Performance

• Geocoding calls are network-bound (~160ms to Apple/Google servers)
• Synchronous operations like calculateDistance are extremely fast (~0.6μs per call)

Installation

yarn add react-native-nitro-geocoder react-native-nitro-modules

iOS

cd ios && pod install

Android

No additional setup required.

Usage

Basic Import

import { Geocoder } from 'react-native-nitro-geocoder'

Check Availability

if (Geocoder.isGeocodingAvailable) {
  console.log('Geocoding is available')
}

Forward Geocoding (Address to Coordinates)

const result = await Geocoder.geocode('Riyadh, Saudi Arabia', 'en')
// {
//   position: { latitude: 24.7136, longitude: 46.6753 },
//   formattedAddress: "Riyadh, Riyadh Province, Saudi Arabia",
//   city: "Riyadh",
//   country: "Saudi Arabia",
//   countryCode: "SA",
//   ...
// }

Reverse Geocoding (Coordinates to Address)

const result = await Geocoder.reverseGeocode(24.7136, 46.6753, 'en')
console.log(result.formattedAddress) // "King Fahd Road, Riyadh, Saudi Arabia"
console.log(result.city)             // "Riyadh"
console.log(result.country)          // "Saudi Arabia"

Multiple Results

const results = await Geocoder.geocodeMultiple('Springfield', 5, 'en')
// Returns up to 5 matching locations

Distance Calculation (Synchronous - Ultra Fast)

// ~0.64μs per call - can do 1.5 million calls/second!
const distance = Geocoder.calculateDistance(
  24.7136, 46.6753,  // Riyadh
  21.4225, 39.8262   // Mecca
)
console.log(`Distance: ${(distance / 1000).toFixed(2)} km`) // ~850 km

Locale Support

// English
const en = await Geocoder.reverseGeocode(35.6762, 139.6503, 'en')
console.log(en.country) // "Japan"

// Arabic
const ar = await Geocoder.reverseGeocode(24.7136, 46.6753, 'ar')
console.log(ar.country) // "المملكة العربية السعودية"

// Japanese
const ja = await Geocoder.reverseGeocode(35.6762, 139.6503, 'ja')
console.log(ja.country) // "日本"

API Reference

Methods

Method	Description
geocode(address, locale)	Address to coordinates
reverseGeocode(lat, lon, locale)	Coordinates to address
geocodeMultiple(address, maxResults, locale)	Get multiple results
calculateDistance(lat1, lon1, lat2, lon2)	Distance in meters (sync)

Properties

Property	Description
isGeocodingAvailable	Check if geocoding is available

Types

interface Position {
  latitude: number
  longitude: number
}

interface Region {
  center: Position
  radius: number
}

interface GeocoderResult {
  position: Position
  formattedAddress: string
  street: string
  city: string
  state: string
  subAdminArea: string
  subLocality: string
  country: string
  countryCode: string
  postalCode: string
  region: Region | null  // iOS only, null on Android
}

Platform Notes

iOS

• Uses CLGeocoder (CoreLocation)
• iOS 14.0+
• No API key required
• Rate limited (~50 req/min)
• Important: iOS does not allow multiple geocoding requests simultaneously. If you send a second request while one is in progress, the first one will be cancelled.

Android

• Uses android.location.Geocoder
• API level 21+
• No API key required
• Check isGeocodingAvailable (some emulators don't support it)

React Hooks

The library includes ready-to-use React hooks:

import {
  useGeocode,
  useReverseGeocode,
  useGeocodeMultiple,
  useDistance,
  useGeocoder,
} from 'react-native-nitro-geocoder'

useReverseGeocode

function MyComponent() {
  const { result, error, loading, reverseGeocode, reset } = useReverseGeocode()

  const handleLookup = async () => {
    await reverseGeocode(24.7136, 46.6753, 'en')
  }

  return (
    <View>
      {loading && <ActivityIndicator />}
      {error && <Text>Error: {error}</Text>}
      {result && <Text>{result.formattedAddress}</Text>}
    </View>
  )
}

useGeocode

const { result, error, loading, geocode, reset } = useGeocode()

await geocode('Riyadh, Saudi Arabia', 'en')

useGeocodeMultiple

const { results, error, loading, geocodeMultiple, reset } = useGeocodeMultiple()

await geocodeMultiple('Springfield', 5, 'en')
// results: GeocoderResult[]

useDistance

const { calculateDistance, calculateDistanceKm } = useDistance()

const meters = calculateDistance(24.7136, 46.6753, 21.4225, 39.8262)
const km = calculateDistanceKm(24.7136, 46.6753, 21.4225, 39.8262)

useGeocoder (Combined)

const {
  isAvailable,
  geocode,
  reverseGeocode,
  geocodeMultiple,
  calculateDistance,
} = useGeocoder()

License

MIT

Credits

Built with Nitro Modules by Marc Rousavy.