Skip to content

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.

Screenshot of API key management in the client dashboard when no key exists

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 27a")

    // 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.