Reliable IP Address Geocoding Microservice on Google App Engine
Improve your application responsiveness.
Nowadays, most applications needs to acquire the geolocation of the device they’re running on in order to improve the user experience, but a lot of things can go wrong: lack of device hardware or capabilities, overzealous permission request mechanisms, or the never-ending Time To First Fix to only name a few.
Sometimes, getting a rough (but fast) approximation of the device location is acceptable:
- Your application doesn’t requires “street level” accuracy and only needs to know the current country/region/city of the device.
- Your application requires “street level” accuracy but can accommodate a fast and approximate location to improve responsiveness or as a fallback mechanism for a smoother user experience.
Assuming you’re aware of the IP address geocoding limitations, one solution to the above would be to leverage the geolocation informations carried by the device IP address.
Geocoding Microservice
Years ago, I wrote such a microservice at Popsy, and released it as open-source. One particularity is that it doesn’t relies on any database or third parties:
The application is meant to be hosted in the Google App Engine standard environment and exposes a single endpoint with no parameters:
$ curl https://<your-project-id>.appspot.com/api/v1/geocoder
{
"lat": 40.714353,
"long": -74.005973,
"country": "US",
"city": "new york",
"region": "ny",
"ip": "31.6.43.126",
}The endpoint doesn’t accept any parameters and will only returns the geolocation of the caller.
How does it work?
The application simply forwards Google App Engine specific headers to the caller in a JSON format. Here’s what the official documentation says about those headers:
X-AppEngine-Country
Country from which the request originated, as an ISO 3166–1 alpha-2 country code. App Engine determines this code from the client’s IP address. Note that the country information is not derived from the WHOIS database; it’s possible that an IP address with country information in the WHOIS database will not have country information in the X-AppEngine-Country header. Your application should handle the special country code ZZ (unknown country).
X-AppEngine-Region
Name of region from which the request originated. This value only makes sense in the context of the country in X-AppEngine-Country. For example, if the country is “US” and the region is “ca”, that “ca” means “California”, not Canada. The complete list of valid region values is found in the ISO-3166–2 standard.
X-AppEngine-City
Name of the city from which the request originated. For example, a request from the city of Mountain View might have the header value mountain view. There is no canonical list of valid values for this header.
X-AppEngine-CityLatLong
Latitude and longitude of the city from which the request originated. This string might look like “37.386051,-122.083851” for a request from Mountain View.
Installation
Following the instructions in the README below, you’ll be able to run and host your microservice in the Google Cloud infrastructure at virtually no costs in less than 5 minutes:
The open-source application above has been made with ❤ and released under the permissive Apache License, so you’re good to go. ️Feel free to clap the publication.
