IPGeolocation Swift SDK

Overview

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

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, 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.0"
)

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 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. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

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

Field	Type	Default	Notes
apiKey	String?	unset	Required for bulk lookup. Optional for single lookup if requestOrigin is set.
requestOrigin	String?	unset	Must be an absolute http or https origin with no path, query string, fragment, or userinfo.
baseURL	String	https://api.ipgeolocation.io	Override the API base URL.
requestTimeout	TimeInterval	10	Maximum time URLSession will wait for new data on an in-flight request (connect, headers, or inter-chunk body inactivity). Must be greater than zero and less than or equal to resourceTimeout . Maps to URLSessionConfiguration.timeoutIntervalForRequest .
resourceTimeout	TimeInterval	30	Maximum total time for the entire request. Must be greater than zero. Maps to URLSessionConfiguration.timeoutIntervalForResource .
maxResponseBodyBytes	Int	33554432	Maximum response body size. The SDK enforces this while streaming the body and throws TransportError as soon as the limit is exceeded. Must be greater than zero.
allowInsecureHTTP	Bool		Off by default. The SDK sends apiKey in the query string, so http:// would transmit it in plaintext. Set to true only for local testing or a trusted proxy where you have accepted the risk.

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

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.

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

• Bulk lookup always requires apiKey . requestOrigin is not enough.
• 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.
• requestOrigin must be an origin only. Do not include a path, query string, fragment, or userinfo.
• 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 Location 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