ArcGIS JavaScript API Key Please

It’s not just technology and underwear that change frequently, software requirements and Terms of Service (TOS) can change quickly too. Even if you don’t do anything, external factors can turn your app into 404 without warning. This can happen for many reasons, including when changes come to the APIs we use. Don’t worry, you are just an API Key away from success in some cases. What API Key? Do I need one? Let’s dive in.

What API Key?

The ArcGIS JavaScript API has been around for a long time. Since the beginning, there has always been free (not Open) access to the JavaScript API, and additional developer subscription levels for the hard-core. With Esri, API Keys were focused on the subscriptions, while smaller and non-revenue generating sites weren’t impacted. This is still partially true, but things are continuing to evolve.

I was building an ArcGIS JavaScript API 4x sample to demonstrate Canadian radar data with Esri. Suddenly, the demo stopped working. I opened the chrome dev console to look for clues. The code syntax looked fine (no missing semicolons, etc). Everything worked 30 seconds ago and I only changed the basemap. It wasn’t until I jumped into the Chrome developer tools’ network window that I noticed something was blocking the Esri JavaScript API. Oh crap, a ”No API Key” error. Wait, what?! Was I no longer able to build my app because I changed the basemap? I tried removing the basemap, but it was too late, the cache had me. I could clear my cache or go and get a developer API Key, but I wanted to know why. Some searching led me to an old/familiar location - the “Getting Started” section of the ArcGIS JavaScript documentation (haven’t been to that page in a while). Looks like API Keys are becoming the norm now with some new requirements for some services (and an updated terms of service).

A Switcheroo?

I’ll admit, I don’t re-read Getting Started pages or TOS documents often. But I was pretty sure just a few years ago an API Key wasn’t a requirement for ArcGIS JavaScript 4x maps (unless you were a developer generating revenue).

As recently as 2018, Esri was promoting that Google developers migrate to the ArcGIS JavaScript API (4x) - One of the selling features mentioned: “You won’t need an API key; you can simply reference the API”. Yeah, that part. That’s only 14 months ago if we don’t include COVID months (since COVID months should never count). Fine, 2.5 years for the purists. To be clear - you don’t need a key to access the JavaScript API, just the services.

Source: Esri Blog Announcement Aug 2018 Migrating from Google Maps JavaScript API to ArcGIS API for JavaScript

Thankfully, the online documentation is now littered with reminders for API Keys if you are looking. The Map class basemap section has a list titled “Basemaps for use with API keys”. That explains the issue from earlier. Another example, the Getting Started section plays it more direct - it mentions these 3 things to get you started:

Setup the API
Get an API key
Start the tutorial

Not a sneaky switcheroo, another change to technology over time. Although, if you migrated from Google based on the 2018 marketing, I could understand if you are a little pissed. One silver lining is that the 2018 article mentioned 1 million free map transactions per month with a developer subscription. Today, that number has increased to 2 million. You can still be pissed, but take the 2 million map requests.

Things Change

This shouldn’t be a surprise as companies review their approaches, TOS, and bank accounts all the time. Providing API Keys for access to enhanced services is the norm, with free services still available in most cases. The ArcGIS JavaScript API integration with Portal Maps, specialized basemaps, enhanced search services (routing and demographics) were all signs it was moving more this way. Yup, Esri recently announced the ArcGIS Platform (PaaS) for developers. Use one of many APIs to access Esri enriched services to build your apps - which is where the API keys come in.

You can work directly with our location services using open-source mapping libraries like Leaflet, GL JS, OpenLayers, and ArcGIS REST JS. _{~Esri ArcGIS Platform (PaaS) blog}

This doesn’t mean it will take your beer money - there is still a free tier with a developer API key and… oh wait, it’s the same as Goog… Yes, a free tier for most services and some premium services are also available. And you don’t need an API key for everything (yet). My demo is back and running without a key and it gets the job done - it’s just a demo and will cap out to less than 2 million monthly requests even if I needed a key. Not that I make any beer money from it anyway.

So, you need an API Key for Google, Esri, and many other services. Not a big deal. If you want to avoid API Keys, you do have other options - but remember, API Keys aren’t evil. OpenStreetMap and the popular Leaflet API both have lots of options. And yes, Esri has an extension to Leaflet to integrate with Esri. However, if you want to use premium Esri services (basemaps, routing, etc), you will still require an Esri API Key (I looked it up, it’s in the docs). On the flip side, you can use whatever API you like and still access premium services with the key. Glass half full.

Esri Developer Terms of Service

Since I was digging into things, I also reviewed the current Terms of Service. There are a few items related to developers creating value-added applications (revenue-generating) that might be of interest to a select few.

Value-added applications built with:

The current generation client APIs (i.e. JavaScript 4.x and Runtime SDKs 100.x) is required to use API Keys in their applications by Aug 1, 2021.

The older generation client APIs (i.e. JavaScript 3.x and Runtime SDKs 10.x) is required to use API Keys in their applications by January 1, 2023.

Source: Developer Products footnote #91 of the Esri Terms of Service e300. The TOS has more details if interested. Also check out footnotes #16 and #64 for JavaScript Web API specific items.

What’s the Point?

The point is, web development is always changing, and so are the requirements to access services. Keep an eye on the APIs and services you use and the changes that are happening. Old applications can be impacted without warning, so don’t forget to check the documentation and requirements before you start pulling your application apart. API Keys are just one of many types of changes. Breaking changes can also be introduced with new API versions (ArcGIS 3x to 4x for example). Heck, my Wyze camera stopped its in-camera person detection one day - Why? The company that made that piece of software (Xnor.ai) was acquired by Apple, so Wyze had to change its terms and no more onboard AI software.

In short, RTFM once a year for all the APIs and web services you use just to make sure everything will keep ticking. As well, a big tech company might buy something and screw your recent home camera purchase.