This answer considers the Geocoding API provided by the Google Maps Platform in addressing the question, as this is the API which the author mentioned in the description of the question.
Using the Geocoding API requires an API key with the appropriate privileges, and to obtain it, one has to set up a billing account in Google Cloud Console. However, the monthly free limit for API calls is so high that it is difficult to imagine exceeding that for academic projects or even small business needs.
To know how to setup the billing account and starting to use the Geocoding API, see the nicely explained guide by Google and the references therein.
Obtain an API key following the instructions there, and then the API calls for geocoding and reverse geocoding can be made.
In geocoding, one needs to provide an address in a prescribed format of GET http request, as described here. Similarly, in reverse geocoding, another GET request has to be made, which is
https://maps.googleapis.com/maps/api/geocode/json?latlng=LATITUDE,LONGITUDE&key=API_KEY
Replace LATITUDE
with the latitude value, LONGITUDE
with the longitude value and API_KEY
with your API key for geocoding. For example, paste the following line (after replacing API_KEY
with your API key) in one of your browser tab to obtain the reverse geocoding response in the JSON format:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=API_KEY
Note that, in this step, there is a mistake in Google's official documentation as on the time of writing this answer: Google's documentation contains this link as an example request for reverse geocoding:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
However, it won't work unless the amp;
phrase is removed. One needs to remove amp;
and replace YOUR_API_KEY
with the API key of yours for geocoding to get the proper results from the GET request.
Now, in the question, LATITUDE
= 37.29978035556258, LONGITUDE
= -75.66096298677134. So, let's form the correct request string (sans the actual API key, which is to be placed by the user):
https://maps.googleapis.com/maps/api/geocode/json?latlng=37.29978035556258,-75.66096298677134&key=API_KEY
After replacing API_KEY
with your own API key, paste the link in a browser tab (or, make a GET request through any programming language or application of your preference). The result obtained (in raw data) is
{
"plus_code" : {
"compound_code" : "78XQ+WJ7 Broadwater, VA, USA",
"global_code" : "879678XQ+WJ7"
},
"results" : [
{
"address_components" : [
{
"long_name" : "78XQ+WJ",
"short_name" : "78XQ+WJ",
"types" : [ "plus_code" ]
},
{
"long_name" : "Broadwater",
"short_name" : "Broadwater",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Northampton County",
"short_name" : "Northampton County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Virginia",
"short_name" : "VA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "78XQ+WJ Broadwater, VA, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 37.299875,
"lng" : -75.66087499999999
},
"southwest" : {
"lat" : 37.29975,
"lng" : -75.661
}
},
"location" : {
"lat" : 37.2997804,
"lng" : -75.660963
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 37.3011614802915,
"lng" : -75.65958851970849
},
"southwest" : {
"lat" : 37.29846351970851,
"lng" : -75.6622864802915
}
}
},
"place_id" : "GhIJq_1CNF-mQkARbTfBN03qUsA",
"plus_code" : {
"compound_code" : "78XQ+WJ Broadwater, VA, USA",
"global_code" : "879678XQ+WJ"
},
"types" : [ "plus_code" ]
},
{
"address_components" : [
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "United States",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 71.5388001,
"lng" : -66.885417
},
"southwest" : {
"lat" : 18.7763,
"lng" : 170.5957
}
},
"location" : {
"lat" : 37.09024,
"lng" : -95.712891
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 71.5388001,
"lng" : -66.885417
},
"southwest" : {
"lat" : 18.7763,
"lng" : 170.5957
}
}
},
"place_id" : "ChIJCzYy5IS16lQRQrfeQ5K5Oxw",
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
So, clearly, the result returns the country as the United States
, as well as the state (administrative_area_level_1
) as Virginia
. Other lower level address components are also returned, e.g., Northampton County
.
If one is not interested in the complete detailed result, optional parameters may be supplied to get only the intended component of the result. For example, if one requires only the country information, the following format would work:
https://maps.googleapis.com/maps/api/geocode/json?latlng=37.29978035556258,-75.66096298677134&result_type=country&key=API_KEY
The result is:
{
"plus_code" : {
"compound_code" : "78XQ+WJ7 Broadwater, VA, USA",
"global_code" : "879678XQ+WJ7"
},
"results" : [
{
"address_components" : [
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "United States",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 71.5388001,
"lng" : -66.885417
},
"southwest" : {
"lat" : 18.7763,
"lng" : 170.5957
}
},
"location" : {
"lat" : 37.09024,
"lng" : -95.712891
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 71.5388001,
"lng" : -66.885417
},
"southwest" : {
"lat" : 18.7763,
"lng" : 170.5957
}
}
},
"place_id" : "ChIJCzYy5IS16lQRQrfeQ5K5Oxw",
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
However, parsing the plus code would yield the state information also.
There are other optional arguments, which are described in the official documentation.
Now, the coordinates given in the question was within the territorial waters of a country. What happens if one gives coordinates of the point in the middle of the ocean to the API call? To see this, let's set LATITUDE
=37.323285561840336, LONGITUDE
=-66.47779150961728 in the API call:
https://maps.googleapis.com/maps/api/geocode/json?latlng=37.323285561840336,-66.47779150961728&key=API_KEY
The following image shows the position of this point in the middle of the ocean:
Result of the API call:
{
"plus_code" : {
"global_code" : "879M8GFC+8V8"
},
"results" : [
{
"address_components" : [
{
"long_name" : "879M8GFC+8V",
"short_name" : "879M8GFC+8V",
"types" : [ "plus_code" ]
}
],
"formatted_address" : "879M8GFC+8V",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 37.323375,
"lng" : -66.47775
},
"southwest" : {
"lat" : 37.32325,
"lng" : -66.477875
}
},
"location" : {
"lat" : 37.3232856,
"lng" : -66.4777915
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 37.3246614802915,
"lng" : -66.4764635197085
},
"southwest" : {
"lat" : 37.3219635197085,
"lng" : -66.47916148029151
}
}
},
"place_id" : "GhIJRaIrbGGpQkARorPMIpSeUMA",
"plus_code" : {
"global_code" : "879M8GFC+8V"
},
"types" : [ "plus_code" ]
}
],
"status" : "OK"
}
Here, only the plus code is there in the address field. This is because the point is outside of the political boundary of any country, and so it does not have an usual descriptive address.
However, one shortcoming of the Google Geocoding API is that it may yield no result if the location is very remote. In such a case, the value of the "status"
field is "ZERO_RESULTS"
.
Now, a query of interest may be to find the name of the nearest country or political territory of a given pair of latitude and longitude coordinates. Unfortunately, the Google Geocoding API is not capable of providing that. It can only provide the latitude and longitude of a given address (geocoding) or the address of a given pair of latitude and longitude (reverse geocoding). Closest location results cannot be obtained from the Google Geocoding API currently. All the required and optional parameters of the API calls for geocoding and reverse geocoding are described here. Getting the closest territorial location from a given point outside any political boundaries would require a program which would make API calls to Geocoding API for points at increasing distance from the given given point, until a territorial address is returned.