Skip to content

README.md

Latest commit

 

History

History
140 lines (92 loc) · 5.21 KB

README.md

File metadata and controls

140 lines (92 loc) · 5.21 KB

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"



// 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
})
### `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 Policy

This library uses BigDataCloud's free client-side reverse geocoding API (api.bigdatacloud.net), governed by the Fair Use Policy.

This API is for resolving the current, real-time location of the calling device only.

Key rules:

  • Client-side only — requests must originate directly from the device being located, not from a server or automated script
  • Real-time coordinates only — only live GPS/WiFi coordinates obtained at the moment of the call are permitted. Pre-stored, cached, or externally-sourced coordinates are strictly not allowed
  • User consent required — coordinates must be obtained via platform geolocation APIs with the user's explicit permission

Violations result in a 402 error and your IP address being banned.

If you need to geocode coordinates you already have, or need server-side geocoding, use the Reverse Geocoding API with a free API key instead — it includes 50,000 free queries per month.

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