Benefits of the 51Degrees Configurator

Go forth and share your API resource keys!

If you've browsed our website or social media profiles before, you may have heard us talk about our configurator. But how can you use the configurator 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 configurator; our tool to help you make keys to access the resources you need.

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

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://configure.51degrees.com/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 where our configurator services are used, 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.

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 in the configurator, 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']

Paid features and license keys

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.

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.

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 51Degrees configurator and start building!