BigDataCloud Swift Client

Official Swift client library for BigDataCloud free APIs — reverse geocoding and roaming detection for iOS, macOS, tvOS and watchOS.

No API key required. Uses api.bigdatacloud.net.

Looking for a full-featured server-side Swift SDK with all BigDataCloud APIs? That's a separate package — coming soon.

Installation

Swift Package Manager

In Xcode: File → Add Package Dependencies and enter:

https://github.com/bigdatacloudapi/bigdatacloud-swift-client

Or add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/bigdatacloudapi/bigdatacloud-swift-client", from: "1.0.0"),
],
targets: [
    .target(name: "YourTarget", dependencies: ["BigDataCloudClient"]),
]

Quick Start

import BigDataCloudClient

let client = BigDataCloudClient()

// Resolves the user's location — GPS preferred, IP fallback if denied
let result = try await client.reverseGeocode()
print("\(result.response.city), \(result.response.countryName)")
print("Accuracy: \(result.accuracy)") // .fine, .coarse, or .ipBased

Location Strategy

The library follows a strict three-tier location priority:

1. Fine (GPS) — always requested first. Best accuracy.
2. Coarse (network/cell) — used automatically when GPS accuracy is reduced.
3. IP-based — only when the user denies all location access. Always clearly indicated via AccuracyLevel.ipBased.

Always show the user what accuracy level is in use — never silently present IP-based results as GPS-based.

let result = try await client.reverseGeocode()

switch result.accuracy {
case .fine:
    print("GPS location: \(result.response.city)")
case .coarse:
    print("Approximate location: \(result.response.city)")
case .ipBased:
    // Inform the user — this is a degraded fallback
    print("IP-based location: \(result.response.city) — enable location for better accuracy")
}

Roaming Detection

let roaming = try await client.amIRoaming()
if roaming.isRoaming == true {
    print("Roaming in \(roaming.roamingCountryName ?? "unknown")")
    print("Home country: \(roaming.simRegisteredCountryName ?? "unknown")")
}

Fair Use Policy

This library uses api.bigdatacloud.net, governed by BigDataCloud's Free Client-Side API Fair Use Policy.

Key rules:

• Client-side only. Requests must originate from the device whose location is being resolved.
• Real-time coordinates only. Only the current, live location of the calling device is permitted. Pre-stored, cached, or externally-sourced coordinates are not allowed.
• User consent required. Coordinates must be obtained via platform geolocation APIs (GPS/WiFi) with the user's permission.

Violations result in a 402 error and IP ban.

If your use case doesn't fit — for example you already have coordinates from another source — use the server-side reverse geocoding API instead. It includes 50,000 free queries per month with an API key.

SwiftUI Example

See Examples/BasicUsage.swift for a complete SwiftUI integration showing location resolution, accuracy badge, and roaming detection.

Info.plist

Add the appropriate location usage description to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>Used to show your current city and country.</string>

Requirements

• iOS 15+ / macOS 12+ / tvOS 15+ / watchOS 8+
• Swift 5.9+
• No external dependencies — Foundation + CoreLocation only

License

MIT — see LICENSE.