Skip to content

JavaScript SDK

Users of JavaScript, TypeScript, and related languages can use our official package to make the most of our APIs. The SDK is written in TypeScript, and the core is generated from our official OpenAPI spec, so you get all the latest documentation and autocomplete in your favorite editor. We offer a variety of module formats, supporting most common environments like web browsers and Node.js.

Looking for maps?

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

Quickstart with npm

Installation

First, install the package via your favorite package manager.

npm install --save @stadiamaps/api

yarn 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" });
// 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" });

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@2.1"></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" });
            // 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>

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.