\r\n

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.

Generated by doxygen 1.8.15