51Degrees API Documentation  4.5

Search

Documentation

• Reverse Geocoding
• Reverse Geocoding Quick Start

Reverse Geocoding Quick Start

Getting Started with Reverse Geocoding🔗

Reverse geocoding turns GPS coordinates into real places like countries, cities, and addresses. Here's how to set it up in minutes.

Step 1: Get Your Resource Key🔗

You'll need a Resource Key to access our reverse geocoding service. Follow the Configurator explanation 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('./index');

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🔗

Your results are in the flowData object (not returned from process()). Each property has a hasValue boolean. If it's populated, hasValue is true and value contains the result. If not, hasValue is false and you'll find why in the null reason property.

C# Java Node.js PHP Python

Select a language.

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

Console.Write($"Awaiting response");

CancellationTokenSource cancellationSource = new CancellationTokenSource();

Task.Run(() => { OutputUntilCancelled(".", 1000, cancellationSource.Token); });

cancellationSource.Cancel();

Console.WriteLine();

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

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();

if (flowData.country.hasValue) {

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

} else {

console.error("Country not available:", flowData.countrynullreason)

}

$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/location-dotnet/blob/master/Examples/Cloud/GettingStarted/Program.cs

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

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

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

https://github.com/51Degrees/location-python/blob/master/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.