51Degrees API Documentation  4.2Newer Version 4.4

Reverse Geocoding

This example demonstrates how to look up a latitude and longitude to a geographical location.

Step 1: create a resource key

First, obtain a resource key by following the Configurator explanation. For this example, ensure that the resource key is authorised for at least the Country field provided by 51Degrees.

Step 2: install the relevant library

Select a language.

Step 3: create a Pipeline and authorise it with the resource key

The pipeline, as explained in the basic pipeline description and Pipeline, is the way to consume 51Degrees APIs. Set the resource key to be the one you obtained above in step 1.

Select a language.

Step 4: create a FlowData on the Pipeline and add evidence to it

For reverse geocoding, two pieces of query data (called evidence) are required: latitude and longitude. Each piece of data is passed to the APIs with a key naming the type of data that it is. The relevant evidence keys for reverse geocoding are:

  • query.51D_pos_latitude
  • query.51D_pos_longitude

Keys are not case-sensitive. Add each piece of evidence with its key.

Select a language.

Step 5: start a query with process()

This actually initiates the query and contacts your data source, whether the 51Degrees cloud API or a local deployment.

Select a language.

Step 6: read the results

Results are available in the existing flowData object (note: they are not returned from the process() call) in an aspect data dictionary with relevant properties. Each property has a hasValue boolean; if the property is populated, flowData.property.hasValue will be true and flowData.property.value will be the relevant value. If the property is not populated, flowData.property.hasValue will be false and flowData.propertynullreason will be populated.

Select a language.

You can get all this code from the examples attached to each library on Github, and other examples as well. See below for the link to the appropriate getting-started example and other examples for each language.

Select a language.


If you are finding unexpected results from querying the APIs, this section may give some indication of where to start debugging.

Invalid resource key

If your resource key is invalid or unrecognised by the server, you should receive a server error reading "Resource key not found", but you may also receive an error like "An invalid IP address was specified. Parameter name: address". In both of these cases, generate a new resource key with access to the properties you require and use that.

Unauthorised resource key

If you find that properties are unexpectedly undefined on your flowData object (for example, if flowData.location.country is not present at all, rather than being present with hasValue false) then your resource key may not be authorised to access any location properties at all. Try generating a new resource key and using it, or visiting https://configure.51degrees.com/YOUR_RESOURCE_KEY to see the properties which that resource key can access. Note that a resource key's properties cannot be changed once created; create a new key instead of trying to edit an existing one.

(If you can inspect the JSON response from the HTTP APIs, you may find that device.geolocationnullreason is set, which is another indicator of this problem.)

Incorrect evidence keys

The list of evidence keys which are used to add evidence must be adhered to. If you provide evidence with an invalid key, it will be ignored. If you do not have any valid keys (or have insufficient valid evidence), then an error like this will be returned:

This property requires evidence values from JavaScript running on the client. It cannot be populated until a future request is made that contains this additional data.

If this happens, check your calls to flowData.evidence.add and ensure that you are using valid evidence keys. There is deliberately no comprehensive list of evidence keys, because they vary depending on source and API queried. For geocoding, the evidence keys that are likely to be useful are

  • query.51d_pos_latitude
  • query.51d_pos_longitude