IPGeolocation.io Swift SDK

Overview

Official Swift SDK for the IPGeolocation.io IP Geolocation API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, time zone, network, hostname, abuse, user-agent, currency, and security data from one API.

• Swift Package targeting Swift 5.9, macOS 12+, iOS 15+, tvOS 15+, and watchOS 8+
• Typed JSON responses plus raw JSON and XML methods
• Built on URLSession with no third-party dependencies

Install

Add the package to your Swift Package Manager dependencies.

Swift Package Manifest:

.package(
    url: "https://github.com/IPGeolocation/ip-geolocation-api-swift-sdk.git",
    from: "1.0.1"
)

Then add IPGeolocation to your target's dependencies:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "IPGeolocation", package: "ip-geolocation-api-swift-sdk"),
    ]
)

Xcode: in File → Add Package Dependencies…, enter the repository URL and pick the latest 1.x release.

Package page: https://github.com/IPGeolocation/ip-geolocation-api-swift-sdk

All public types live in the IPGeolocation module. Xcode will import the types you use in the examples below automatically.

Quick Start

import Foundation
import IPGeolocation

struct MissingAPIKey: Error {}

func lookupExample() async throws {
    guard let apiKey = ProcessInfo.processInfo.environment["IPGEO_API_KEY"] else {
        throw MissingAPIKey()
    }

    let client = IPGeolocationClient(
        config: try IPGeolocationClientConfig(apiKey: apiKey)
    )
    defer { client.close() }

    let response = try await client.lookupIPGeolocation(
        LookupIPGeolocationRequest(ip: "8.8.8.8")
    )

    print(response.data.ip ?? "-")                          // 8.8.8.8
    print(response.data.location?.countryName ?? "-")       // United States
    print(response.data.location?.city ?? "-")
    print(response.data.timeZone?.name ?? "-")
    print(response.metadata.creditsCharged ?? 0)
}

You can also call lookupIPGeolocation() with no request object to resolve the caller IP.

At a Glance

Get Your API Key

Create an IPGeolocation.io account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

For server-side Swift code, keep the API key in an environment variable or a secret manager.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

Config values are validated when the config is built. The initializer throws ValidationError on invalid input. Request values are validated before each request is sent.

URLSession does not expose a connect-only timer, so the SDK uses URLSession's native two-knob model: requestTimeout is the inactivity timer that also fires on a stalled body read, and resourceTimeout caps the total time. This is honest about the behavior you actually get on iOS and macOS.

Available Methods

Request Options

var request = LookupIPGeolocationRequest(ip: "8.8.8.8")
request.languageCode = "ar"
let response = try await client.lookupIPGeolocation(request)

JSON Keys and Swift Names

The API returns JSON keys such as country_metadata and calling_code. In Swift code, the SDK uses countryMetadata and callingCode.

The data is the same. Only the names you use in Swift change.

Example:

1{
2  "country_metadata": {
3    "calling_code": "+46"
4  },
5  "time_zone": {
6    "current_tz_abbreviation": "CET"
7  },
8  "location": {
9    "is_eu": true
10  }
11}

print(response.data.countryMetadata?.callingCode ?? "-")
print(response.data.timeZone?.currentTZAbbreviation ?? "-")
print(response.data.location?.isEU ?? false)

There are two different places where names show up:

• In Swift code, use the names shown by the SDK, such as response.data.countryMetadata?.callingCode
• In request parameters, use the API names from the documentation

include example:

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "8.8.8.8",
        include: ["user_agent"]
    )
)

print(response.data.userAgent?.name ?? "-")

fields example:

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "8.8.8.8",
        fields: ["country_metadata.calling_code"]
    )
)

print(response.data.countryMetadata?.callingCode ?? "-")

excludes example:

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "8.8.8.8",
        excludes: ["time_zone.current_tz_abbreviation"]
    )
)

print(response.data.timeZone?.currentTZAbbreviation ?? "-")

More request-parameter examples:

• include: ["security", "abuse"]
• include: ["hostnameFallbackLive"]
• fields: ["country_metadata.calling_code"]
• fields: ["time_zone.current_tz_abbreviation"]
• excludes: ["location.is_eu"]

Examples

The examples below assume you already have a configured client in scope:

import Foundation
import IPGeolocation

let apiKey = ProcessInfo.processInfo.environment["IPGEO_API_KEY"] ?? ""
let client = IPGeolocationClient(
    config: try IPGeolocationClientConfig(apiKey: apiKey)
)

let response = try await client.lookupIPGeolocation()
print(response.data.ip ?? "-")

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(ip: "ipgeolocation.io")
)

print(response.data.domain ?? "-")                    // ipgeolocation.io
print(response.data.location?.countryName ?? "-")

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "9.9.9.9",
        include: ["security", "abuse"]
    )
)

print(response.data.security?.threatScore ?? 0)
print(response.data.abuse?.emails?.first ?? "-")

let visitorUA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "115.240.90.163",
        include: ["user_agent"],
        userAgent: visitorUA
    )
)

print(response.data.userAgent?.name ?? "-")
print(response.data.userAgent?.operatingSystem?.name ?? "-")

let response = try await client.lookupIPGeolocation(
    LookupIPGeolocationRequest(
        ip: "8.8.8.8",
        include: ["security"],
        fields: [
            "location.country_name",
            "security.threat_score",
            "security.is_vpn",
        ],
        excludes: ["currency"]
    )
)

print(response.data.location?.countryName ?? "-")
print(response.data.security?.isVPN ?? false)
print(response.data.currency == nil)

let response = try await client.lookupIPGeolocationRaw(
    LookupIPGeolocationRequest(ip: "8.8.8.8", output: .xml)
)

print(response.data)

let response = try await client.bulkLookupIPGeolocation(
    BulkLookupIPGeolocationRequest(ips: ["8.8.8.8", "1.1.1.1"])
)

for result in response.data {
    if result.isSuccess {
        print(result.data?.ip ?? "-")
    } else {
        print(result.error?.message ?? "-")
    }
}

let response = try await client.bulkLookupIPGeolocationRaw(
    BulkLookupIPGeolocationRequest(ips: ["8.8.8.8", "1.1.1.1"])
)

print(response.data)

Response Metadata

Every method returns APIResponse<T>, where:

• data contains the typed object or raw response string
• metadata contains response details such as:
  • creditsCharged
  • successfulRecords
  • statusCode
  • durationMs
  • rawHeaders

Example:

print(response.metadata.statusCode)
print(response.metadata.durationMs)
print(response.metadata.firstHeaderValue("content-type") ?? "-")

JSON Helpers

Use JSONOutput for logs, debugging, or CLI output.

Example:

let compact = try JSONOutput.toPrettyJSON(response.data)
let full = try JSONOutput.toPrettyJSON(response.data, mode: .full)

print(compact)
print(full)

Errors

All SDK errors conform to the IPGeolocationError protocol. If a request error includes your configured API key, the SDK replaces it with [REDACTED]. HTTP errors keep their status code even when the error response cannot be read. Some error details may be shortened to keep the key hidden.

APIError exposes:

• statusCode
• message
• apiMessage
• kind (APIErrorKind, which covers .badRequest, .unauthorized, .forbidden, .notFound, .methodNotAllowed, .contentTooLarge, .unsupportedMediaType, .locked, .tooManyRequests, .clientClosedRequest, .internalServerError, .other)

Example:

do {
    _ = try await client.lookupIPGeolocation(
        LookupIPGeolocationRequest(ip: "8.8.8.8", output: .xml)
    )
} catch let error as ValidationError {
    print(error.message)
}

Troubleshooting

• Set apiKey before making a lookup.
• Typed methods only support JSON. Use the raw methods for XML.
• If you need security, abuse, user-agent, or hostname data, include those modules explicitly.
• fields and excludes filter the response. They do not unlock paid data.
• Response fields are optional so omitted fields stay omitted.
• requestTimeout must be less than or equal to resourceTimeout.
• The SDK rejects responses larger than maxResponseBodyBytes. The default cap is 32 MiB.

Frequently Asked Questions

Links

• Homepage: https://ipgeolocation.io
• IP Geolocation API product page: https://ipgeolocation.io/ip-location-api.html
• Documentation: https://ipgeolocation.io/documentation/ip-location-api.html
• GitHub repository: https://github.com/IPGeolocation/ip-geolocation-api-swift-sdk