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.

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"



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

How It Works

GPS first — GeoLocation.detect() requests device GPS coordinates via the geolocator package
Automatic fallback — If GPS is unavailable, denied, or times out, the API automatically resolves location from the device's IP address
Reverse geocode — Coordinates (or IP) are sent to BigDataCloud's free API endpoint which returns locality data
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
})


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