51Degrees API Documentation  4.5

Documentation

• Reverse Geocoding
• Reverse Geocoding quick start

Reverse Geocoding quick start

Getting started with Reverse Geocoding🔗

Reverse geocoding converts latitude and longitude to location details such as countries, cities, and addresses. Follow these steps to set it up.

Step 1: Get your Resource Key🔗

You'll need a Resource Key to access our reverse geocoding service. Follow the Resource Key guide to create one. Make sure your Resource Key includes at least the Country field.

Step 2: Install the library🔗

C# Java Node.js PHP Python

Select a language.

Install the FiftyOne.GeoLocation package via Nuget.

Install the com.51degrees.pipeline.geo-location package via Maven.

Install the fiftyone.geolocation package from NPM with npm install fiftyone.geolocation

Install the 51degrees/fiftyone.geolocation package using Composer with composer require 51degrees/fiftyone.geolocation

Install the fiftyone-location package from PyPI with pip install fiftyone-location.

Step 3: Set up your pipeline🔗

The pipeline is how you connect to 51Degrees APIs (learn more in basic pipeline description and Pipeline). Use the Resource Key you created in step 1.

C# Java Node.js PHP Python

Select a language.

string resourceKey = "AAAAAAABBBBBBCCCCCC";

using (var pipeline =

new GeoLocationPipelineBuilder(_loggerFactory)

.UseCloud(resourceKey, FiftyOne.GeoLocation.Core.GeoLocationProvider.FiftyOneDegrees)

.UseLazyLoading(TimeSpan.FromSeconds(10))

.Build())

{

...

}

/* See full example code for required imports */

String resourceKey = "AAAAAAABBBBBBCCCCC";

Pipeline pipeline = new GeoLocationPipelineBuilder(loggerFactory)

.useCloud(resourceKey, Enums.GeoLocationProvider.FiftyOneDegrees)

.setEndPoint("https://cloud.51degrees.com/api/v4")

.useLazyLoading(1000)

.setAutoCloseElements(true)

.build();

const FiftyOneDegreesGeoLocation = require('fiftyone.geolocation');

let localResourceKey = 'AAAAAAAABBBBBBCC';

const pipeline = new FiftyOneDegreesGeoLocation.GeoLocationPipelineBuilder({

resourceKey: localResourceKey

}).build();

require(__DIR__ . "/vendor/autoload.php");
use fiftyone\pipeline\geolocation\GeoLocationPipelineBuilder;
$resourceKey = "AAAAAAAABBBBBBCC";
$settings = array(
    "resourceKey" => $resourceKey,
    "locationProvider" => "fiftyonedegrees"
);
$builder = new GeoLocationPipelineBuilder($settings);
$pipeline = $builder->build();

from fiftyone_location.location_pipelinebuilder import LocationPipelineBuilder

resourceKey = "AAAAAAAABBBBBBCC"

pipeline = LocationPipelineBuilder({"resourceKey": resourceKey}).build()

Step 4: Add your coordinates🔗

You need to provide latitude and longitude coordinates (called evidence). Use these specific keys:

• query.51D_pos_latitude
• query.51D_pos_longitude

The keys aren't case-sensitive.

C# Java Node.js PHP Python

Select a language.

var data = pipeline.CreateFlowData();

data.AddEvidence("query.51D_Pos_latitude", "51.458048");

data.AddEvidence("query.51D_Pos_longitude", "-0.9822207999999999");

FlowData flowData = pipeline.createFlowData();

flowData.addEvidence(EVIDENCE_GEO_LAT_PARAM_KEY, "51.458048")

.addEvidence(EVIDENCE_GEO_LON_PARAM_KEY, "-0.9822207999999999")

.process();

const flowData = pipeline.createFlowData();

const latitude = "51.457739";

const longitude = "-0.975978";

flowData.evidence.add('query.51D_Pos_latitude', latitude);

flowData.evidence.add('query.51D_Pos_longitude', longitude);

$flowData = $pipeline->createFlowData();

$latitude = "51.457739";

$longitude = "-0.975978";

$flowData->evidence->set('query.51D_Pos_latitude', $latitude);

$flowData->evidence->set('query.51D_Pos_longitude', $longitude);

fd = pipeline.create_flowdata()

latitude = "51.457739"

longitude = "-0.975978"

fd.evidence.add("query.51D_Pos_latitude", latitude)

fd.evidence.add("query.51D_Pos_longitude", longitude)

Step 5: Run the query🔗

Call process() to start the reverse geocoding lookup.

C# Java Node.js PHP Python

Select a language.

data.Process();

(see previous step)

await flowData.process()

$result = $flowData->process();

fd.process()

Step 6: Get your results🔗

Read the results from the flow data once process() has finished, as the snippets below show. Each property says whether it has a value (HasValue in C#, hasValue() in Java, hasValue in Node.js and PHP, and has_value() in Python). If it does, its value is the result. If not, its no value message says why.

C# Java Node.js PHP Python

Select a language.

var country = data.Get<IGeoData>().Country;

// With lazy loading, reading the value waits for the result, up to the

// timeout set in step 3.

if (country.HasValue)

{

Console.WriteLine($"Country: {country.Value}");

}

else

{

Console.WriteLine($"Country: {country.NoValueMessage}");

}

AspectPropertyValue<String> country = flowData.get(GeoData.class).getCountry();

Future future = flowData.get(GeoData.class).getProcessFuture();

System.out.print("Awaiting response");

System.out.println(flowData.get(CloudRequestData.class).getJsonResponse());

System.out.println("Country: " + country.toString());

pipeline.close();

const country = flowData.location.country;

if (country.hasValue) {

console.log("Country name:", country.value)

} else {

console.error("Country not available:", country.noValueMessage)

}

$country = $flowData->location->country;

if ($country->hasValue) {

echo "Which country is the location [" . $latitude . "," . $longitude . "] in?";

echo "<br />";

echo $flowData->location->country->value;

} else {

// Echo out why the value isn't meaningful

echo $country->noValueMessage;

};

if fd.location.country.has_value():

print(fd.location.country.value())

else:

print(fd.location.country.no_value_message())

Find complete working code examples on GitHub for each language:

C# Java Node.js PHP Python

Select a language.

https://github.com/51Degrees/51degrees-dotnet/blob/main/location/Examples/Cloud/GettingStarted/Program.cs

https://github.com/51Degrees/51degrees-java/blob/main/location/geo-location.shell.examples/src/main/java/fiftyone/geolocation/examples/cloud/GettingStarted.java

https://github.com/51Degrees/51degrees-node/blob/main/location/examples/gettingStarted.js

https://github.com/51Degrees/51degrees-php/blob/main/location/examples/cloud/gettingstarted.php

https://github.com/51Degrees/51degrees-python/blob/main/location/examples/cloud/gettingstarted.py

Troubleshooting🔗

Having issues? Here are common problems and fixes:

Resource Key problems🔗

"Resource Key not found" error: Your Resource Key is invalid. Create a new one with the properties you need.

Properties missing from results: Your Resource Key might not have access to location properties. Check what your key can access at https://configure.51degrees.com/YOUR_RESOURCE_KEY or create a new key with the right permissions.

Wrong evidence keys🔗

If you get an error about missing evidence, check you're using the correct keys:

• query.51d_pos_latitude
• query.51d_pos_longitude

Wrong keys get ignored, which can cause errors if you don't have any valid evidence.

Have a data or code question? Get in touch and explore subscription options.