Skip to content

JavaScript SDK

Add geocoding, search, routing, and more to your website or app with just a few lines of code.

The Stadia Maps JavaScript SDK is the easiest way to use our location APIs in websites, Node.js applications, or React Native apps. It includes built-in type information and comprehensive docstrings straight from our official specs. There's no easier way to discover the flexibility of our APIs with JavaScript or TypeScript.

Looking for maps?

If you're building interactive maps for your website, head over to interactive web maps guide.

Quickstart with npm

Installation

The Stadia Maps JavaScript/TypeScript SDK is available for any package manager that supports the npm registry.

NPM Downloads

npm install @stadiamaps/api

yarn add @stadiamaps/api

bun add @stadiamaps/api

You can now use this in your JS or TS project just like any other package! You'll first need to set up a client (possibly with an API key, depending on your use case) for the API group you want to access.

Example Code

Here's a quick usage example of how to set up a client and do some geocoding.

import { GeocodingApi, Configuration } from '@stadiamaps/api';

// Most users can use our domain-based or localhost authentication methods (see https://docs.stadiamaps.com/authentication/).
//
// If you are writing for a backend application or can't use domain-based auth,
// then you'll need to add your API key like so:
// 
// const config = new Configuration({ apiKey: "YOUR-API-KEY" }); (1)
// You can also use our EU endpoint to keep traffic within the EU using the basePath option:
// const config = new Configuration({ basePath: "https://api-eu.stadiamaps.com" });
// const api = new GeocodingApi(config);
const api = new GeocodingApi();

// Make an API call! The responses use the standard promise API.
// You can use either the callback interface...
api.reverse({ pointLat: 59.44436, pointLon: 24.75071 }).then(function (result) {
    console.log(result);
}, function (err) {
    console.log(err);
});

// ... or the await keyword in an async context
const res = await api.search({ text: "Põhja pst 27" });
  1. Learn how to get an API key in our authentication guide.

Quickstart with unpkg

If you like to keep your frontend simple and don't want to use JS build tooling, we have you covered! You can easily use the SDK by linking to the module on unpkg. The library is exported via the global stadiaMapsApi, but otherwise functions exactly as if you used npm package tooling.

Here's a quick usage example of a webpage that makes a geocoding query and displays the result.

Try it in JSFiddle 
<!DOCTYPE html>
<html>
    <head>
        <script type="text/javascript" src="https://www.unpkg.com/@stadiamaps/api@3"></script>
        <script type="text/javascript">
            // In nearly all cases, you should be able to construct any of the APIs as-is (see https://docs.stadiamaps.com/authentication/).
            // If you really need an API key, you can add it like so:
            // const config = new stadiaMapsApi.Configuration({ apiKey: "YOUR-API-KEY" }); (1)
            // You can also use our EU endpoint to keep traffic within the EU using the basePath option:
            // const config = new Configuration({ basePath: "https://api-eu.stadiamaps.com" });
            // const api = new stadiaMapsApi.GeocodingApi(config);
            const api = new stadiaMapsApi.GeocodingApi();
            window.onload = async function() {
                // You can use either the async interface or the other Promise API functions like .then; the choice is yours.
                const res = await api.autocomplete({ text: "Põhja pst 27" });
                document.getElementById("pre").innerHTML = JSON.stringify(res, null, 2);
            }
        </script>
    </head>

    <body>
        <div>
            <pre id="pre">Loading...</pre>
        </div>
    </body>
</html>
  1. Learn how to get an API key in our authentication guide.

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

Source Code

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