The problem
You have geographic coordinates (longitude and latitude) and you want to know which country the location they respresent is in.Background
Converting geocoordinates (longitude, latitude) into location information is the process know as reverse geocoding. You can pass coordinates to the OpenCage geocoding API to reverse geocode the coordinates and return information like which country the coordinates are in.
When you send a request to the OpenCage Geocoding API with each result we
return (if possible, see the note below about locations that are not part
of any country) various fields about the country of the result.
Specifically within the
components
portion of each result we return
-
country
the name of the country. Example value:Germany
-
ISO_3166-1_alpha-3
the ISO 3116-1 alpha-3 code for the territory. Example value:DEU
-
ISO_3166-1_alpha-2
the ISO 3116-1 alpha-2 code for the territory. Example value:DE
-
country_code
a two-letter code for the country. Example value:de
country
value by setting the optional
language
parameter when you make your API request.
See the API reference
.
As an example if you set
language=de
(ie German)
the returned
country
value will be
Deutschland
.
You may ask, why return both the alpha-2 code and the country_code?
For historical reasons many territories have their own ISO 3116-1 codes,
despite legally being part of another country. An example is Puerto Rico
which has alpha-2 code
PR
,
despite being part of the United States
US
.
Disputed territories
Many areas of the world are disputed or claimed by more than one country. In this case our geocoding API returns whatever in in OpenStreetMap. You can see a list of disputed territories on the OpenStreetMap wiki Our API returns whichever country OpenStreetMap deams to be valid.
It's worth nothing that the process of assigning ISO codes is not
particularly quick, it may be some time before a "new" country has an
official ISO code. As an example, Kosovo, recognized as a sovereign state
by 98 UN member states, does not yet have an official ISO code. In
this case we return just a
country_code
.
Locations that belong to no country
Surprisingly, most of the world - the oceans and Antartica - does not
belong to any country. In this case our geocoder will return neither a
country
value, nor
ISO_3166-1_alpha-2
,
ISO_3166-1_alpha-3
,
or
country_code
values in the
components
portion of the API result.
Because a user’s location is private information, browser geolocation is only possible if the user explicitly grants permission to a web service via a browser prompt. You can see an example of how this can look on these screenshot taken from the OpenCage demo page.
Code Example
Here's a small example of making a reverse geocoding request to the OpenCage API in javascript to detrmine the country of coordinates. We also have SDKs for over 30 other programming languages.
<script>
var apikey = 'YOUR-API-KEY';
var coords = '50.97755,11.32860'; // lat,lng
var api_url = 'https://api.opencagedata.com/geocode/v1/json'
var request_url = api_url
+ '?'
+ 'key=' + apikey
+ '&q=' + encodeURIComponent(coords)
+ '&pretty=1'
+ '&no_annotations=1';
// see full list of required and optional parameters:
// https://opencagedata.com/api#forward
var request = new XMLHttpRequest();
request.open('GET', request_url, true);
request.onload = function() {
// see full list of possible response codes:
// https://opencagedata.com/api#codes
if (request.status === 200){ // Success!
var data = JSON.parse(request.responseText);
var country = 'no country returned';
if (data.results[0].components.country != null){
country = data.results[0].components.country;
}
console.log('country: ' + country);
} else {
console.log("unable to geocode! Response code: " + request.status);
var data = JSON.parse(request.responseText);
console.log('error msg: ' + data.status.message);
}
};
request.onerror = function() {
// There was a connection error of some sort
console.log("unable to connect to server");
};
request.send(); // make the request
</script>
Further Reading
-
OpenCage API reference section discussing the various parts of the
components
portion of geocoding results - OpenCage Javascript tutorial
- OpenCage Guide to reverse geocoding