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


// 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
})

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

### `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`:

```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