bigdatacloud_reverse_geocode_client 1.0.0

Free reverse geocoding for Flutter/Dart — get city, country, and locality from GPS coordinates with automatic IP geolocation fallback. No API key needed.

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.

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:

• Reverse Geocoding — Full-featured server-side reverse geocoding with extended data
• IP Geolocation — Detailed IP-based location data
• Network Engineering — ASN, carrier, and network data

Visit bigdatacloud.com for the complete API catalogue.

License

MIT License — see LICENSE for details.

Copyright © BigDataCloud Pty Ltd