Benefits of 51Degrees resource keys

Benefits of 51Degrees resource keys

Go forth and share your API resource keys!

Developers Device Detection

If you've browsed our website or social media profiles before, you may have heard us talk about our configuration page. But how can you use the configuration page and resource keys to their fullest potential?

An introduction to API keys

If you're using 51Degrees APIs (whether that's reverse geocoding, device detection, or anything else) you need an API key.

Because of the wide variety of data resources which can be assigned to an API key, each key is created with access only to the resources that its application needs. For example, if you need an API key for a reverse geocoding API, you would only select the relevant location-based properties.

And to create your API resource key? You use the configuration page; our tool to help you make keys to access the resources you need.

Full documentation for how to use the configuration page, including a further detailed walkthrough, is included as part of our documentation.

The 51Degrees configuration page
A screenshot of our configuration page.

Why separate resouce keys?

Sometimes we're asked: why is an API resource key tied to a list of resources? Why not simply have one resource key that can do everything?

Firstly, having multiple keys allows you to share your key with pre-populated data.

The easiest way to help someone understand which properties their key needs is to send them a link to yours! Keys that use freely available resources are not secret; you can send someone the URL https://51degrees.com/configure/YOUR_RESOURCE_KEY and that shows which properties that key is tied to.

Similarly, when you create a key, you're also given an alternative URL for that key which can also be shared. You can use this URL to share your key on social networks so others can see your property configuration.

Let's go through an example. You see Which Three Birdies, an amazing resource built with one of our resource keys, and you want to replicate this resource with other APIs of your choosing. We can share the resource key used to create Which Three Birdies, allowing you to jump right in to the development of your own API.

Which Three Birdies website
Which Three Birdies, which used our reverse geocoding properties from our configuration page.

It's important to note that resource keys can't be changed once they are created.

What this means is that keys are customized to the application they're used in and so are unique to your preferences. So, by sharing your resource keys with others, you prevent any properties they need being missed.

The key's assigned resources are the ones returned when making calls to the APIs: in this Python code example, you can see that the shared Which Three Birdies key from earlier has properties of 'town', 'county', 'region', 'state', 'country', and 'countrycode' assigned to it. If you look at that key on the configuration page, you can see those are some of the properties assigned.

See the developer documentation for the reverse geocoding APIs for more on this, including examples in C#, Java, Node.js, and PHP.


from fiftyone_location.location_pipelinebuilder import LocationPipelineBuilder
key='AQQNRUQFJWB2xxWO2Eg' # the Which 3 Birdies key from above
pipeline = LocationPipelineBuilder({'resourceKey': key}).build()
fd = pipeline.create_flowdata()
fd.evidence.add('query.51D_Pos_latitude', '40.730610')
fd.evidence.add('query.51D_Pos_longitude', '-73.935242')
fd.process()
print(fd.location.get_properties().keys())
# prints:
# ['javascript', 'town', 'county', 'region', 'state', 'country', 'countrycode']

Having separate resource keys also allows separate configurations for different apps. For example, some of the properties available via the 51Degrees APIs are paid for; they require an additional license key as part of a commercial relationship.

You can therefore generate a resource key which has access to those properties by associating it with your paid license key, and a separate free resource key which does not have access to those paid properties.

The configuration page asking for a license key
The configuration page will ask you for your license key.

With two types of keys available, it might seem a little confusing. If you've already decided which pricing plan you want to use (whether that's free or paid, cloud or on-premise), here's a guideline for what keys you'll need.

Subscription Resource Key License Key
Free - Cloud x
Free - On-Premise x
Big - Cloud x x
Bigger - Cloud x x
Biggest/Bespoke - Cloud x x
Biggest/Bespoke - On-Premise x

A benefit of license keys is that they are less restricted in usage, while free keys have a usage cap. Free keys are limited to 500,000 monthly requests, whereas paid keys are able to have at least 2,500,000 monthly requests.

Keep your license keys secret, but resource keys using only free properties can be published, shared, or embedded in open source code examples or similar without trouble. This allows you to manage different branches or deployments of your apps separately.

So, grab your next key from the configuration page and start building!