bigdatacloud_reverse_geocode_client

Free reverse geocoding for Flutter & Dart — detect city, country, and locality from GPS with automatic IP fallback. No API key needed.

pub package

Powered by BigDataCloud's free reverse geocoding API with patented geocoding accuracy.

Install

Add to your pubspec.yaml:

dependencies:
  bigdatacloud_reverse_geocode_client: ^1.0.0

Then run:

flutter pub get

Quick Start

import 'package:bigdatacloud_reverse_geocode_client/bigdatacloud_reverse_geocode_client.dart';

// Auto-detect: GPS first, IP fallback
final location = await GeoLocation.detect();
print('${location.city}, ${location.countryName}'); // "Adelaide, Australia"

// Reverse geocode specific coordinates
final coords = await GeoLocation.reverseGeocode(
  latitude: -34.9285,
  longitude: 138.6007,
);

// IP geolocation only (no coordinates)
final ipLocation = await GeoLocation.reverseGeocode();

// Multi-language support
final jaLocation = await GeoLocation.detect(language: 'ja');
print(jaLocation.countryName); // "日本"

How It Works

  1. GPS first — GeoLocation.detect() requests device GPS coordinates via the geolocator package
  2. Automatic fallback — If GPS is unavailable, denied, or times out, the API automatically resolves location from the device's IP address
  3. Reverse geocode — Coordinates (or IP) are sent to BigDataCloud's free API endpoint which returns locality data
  4. No API key — The client endpoint is completely free with no authentication required

API Reference

GeoLocation.detect()

Automatically detects the user's location. Tries GPS first, falls back to IP geolocation.

static Future<LocationData> detect({
  String language = 'en',  // ISO 639-1 language code
  int timeout = 10,        // GPS timeout in seconds
})

GeoLocation.reverseGeocode()

Reverse geocode specific coordinates, or use IP geolocation if no coordinates provided.

static Future<LocationData> reverseGeocode({
  double? latitude,        // GPS latitude (optional)
  double? longitude,       // GPS longitude (optional)
  String language = 'en',  // ISO 639-1 language code
})

LocationData Fields

Field Type Description
latitude double Latitude of the resolved location
longitude double Longitude of the resolved location
lookupSource String "coordinates" or "ipGeolocation"
continent String Continent name
continentCode String Continent code (e.g., "OC")
countryName String Country name
countryCode String ISO 3166-1 alpha-2 country code
principalSubdivision String State/province/region
principalSubdivisionCode String Subdivision code
city String City name
locality String Locality/suburb name
postcode String Postal/zip code

Android / iOS Setup

Since this package uses GPS via geolocator, you need to configure platform permissions:

Android

Add to android/app/src/main/AndroidManifest.xml:

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

iOS

Add to ios/Runner/Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to your location to provide relevant local information.</string>

Why BigDataCloud?

  • Free — No API key, no signup, no credit card
  • Patented accuracy — BigDataCloud's boundary datasets use proprietary geocoding technology
  • 100+ languages — Locality names in over 100 languages via the language parameter
  • Fast — Global CDN-backed API with low latency
  • Privacy-friendly — IP geolocation fallback means you can get approximate location without GPS permissions

Fair Use

The free client API is intended for moderate use from end-user devices. For high-volume server-side usage, please use the authenticated API with an API key.

Need More?

BigDataCloud offers a full suite of geocoding and IP intelligence packages:

Visit bigdatacloud.com for the complete API catalogue.

License

MIT License — see LICENSE for details.

Copyright © BigDataCloud Pty Ltd

Libraries

bigdatacloud_reverse_geocode_client