Swift SDK¶

We make it easy to integrate the Stadia Maps APIs into your Swift applications with our official SDK. Xcode users will get all the goodies like autocomplete, type definitions, and documentation as you type. All API methods leverage the async features introduced in Swift 5.5, which make it easier than ever to write correct asynchronous code. And since it's generated from official OpenAPI spec, you'll be among the first to get access to our latest features.

Quickstart¶

Installation with Swift Package Manager¶

The Xcode UI changes frequently, but you can add this just like you would any other Swift package. At the time of this writing, the "Add Packages" option is in the Xcode File menu. From the add package screen, search using our repository URL: https://github.com/stadiamaps/stadiamaps-api-swift.

You can find the latest instruction from Apple here.

Getting an API Key¶

Next, you'll need to generate an API key.

1. Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
2. Click "Manage Properties."
3. If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
4. Under "Authentication Configuration," you can generate, view or revoke your API key.

Video: How to generate your API key¶

Then, configure header-based authentication using the StadiaMapsAPI singleton. This code typically goes in your application init method.

// Import (at the top of your file)
import StadiaMaps

// Put this inside your SwiftUI main function, application(_:didFinishLaunchingWithOptions:), or
// similar method early in your app's lifecycle.
StadiaMapsAPI.customHeaders = ["Authorization": "Stadia-Auth YOUR-API-KEY"]

// Optionally use our EU endpoint to keep traffic within the EU
// StadiaMapsAPI.basePath = "https://api-eu.stadiamaps.com"

Example Code¶

Here's a quick example function that does some geocoding. Note that we have designed the SDK with Swift 5.5 async out of the box. If you have not yet adopted async/await in your Swift codebase, you can use the Task API to call async functions in a non-async context. Apple also has a great WWDC talk where you can learn more about async/await.

func myFunction() async throws {
    let res = try await GeocodingAPI.autocomplete(text: "Põhja pst 27")

    // Update your UI etc.
} 

You can find additional usage examples on the endpoint documentation pages.

Source Code¶

Our Swift SDK is completely open source! You can find the source code on GitHub.