This site provides free city-level geolocation services via JSON responses over SSL.
Make your visitor's browser fetch https://city-check.appspot.com/json to get a short JSON document about what IP address was used to reach it. The JSON document includes a city-level geolocation data and critical metadata, in useful machine formats, and also the English language.
Servers can verify the token by fetching /check/<token> and comparing the JSON response. All data is stored for 30 minutes, and the server should check IP address and timestamp make sense.
| city | Columbus | ||
|---|---|---|---|
| country_code | US | ISO 3166-1 alpha-2 country code | |
| timestamp | 1782117022.341 | Unix epoc timestamp as a float (UTC) | |
| region | oh | Short code for region, such as province or state | |
| city_latlng | 39.962511,-83.003222 | Lat, long of centroid of city | |
| city_geohash | dphgr4yykxzz | Geohash of city lat/long | |
| token | 2IA7YeD87tPnA8yhixxR8F9W | Random token valid for verification | |
| referer | None | Copy of Referer header seen by server | |
| human_region | Ohio, USA | Nicely rendered English just region + country | |
| ip | 216.73.216.254 | May be IPv4 or IPv6 format | |
| country | USA | English name of country | |
| human_city | Columbus, Ohio, USA | Nicely rendered English text of city + region + country | |
| region_name | Ohio | Expanded English text for region where possible (US/Canada) |
The visitor's browser can use the JSON directly (for example, with AngularJS or Ember.JS) and then PUT the received token to your server. Your server code should then fetch it's own copy of the JSON data directly from the /check/<token> response. Verification can be performed on the IP field, and timestamp... or you can trust people.
| Client Side | Server Side |
|---|---|
% curl https://city-check.appspot.com/json
{
"city": "Toronto",
"city_geohash": "dpz83dffmxpu",
"city_latlng": "43.653226,-79.383184",
"country": "Canada",
"country_code": "CA",
"human_city": "Toronto, Ontario, Canada",
"human_region": "Ontario, Canada",
"ip": "216.223.156.255",
"referer": null,
"region": "on",
"region_name": "Ontario"
"timestamp": "1365513643.996",
"token": "oSHesz8OIsrlSuEK4VKwLg28",
}
|
% curl https://city-check.appspot.com/check/oSHesz8OIsrlSuEK4VKwLg28
{
"city": "Toronto",
"city_geohash": "dpz83dffmxpu",
"city_latlng": "43.653226,-79.383184",
"country": "Canada",
"country_code": "CA",
"human_city": "Toronto, Ontario, Canada",
"human_region": "Ontario, Canada",
"ip": "216.223.156.255",
"referer": null,
"region": "on",
"region_name": "Ontario"
"timestamp": "1365513643.996",
"token": "oSHesz8OIsrlSuEK4VKwLg28",
}
|
To support Cross-Origin Requests, the appropriate header (access-control-allow-origin: *) is provided in all responses, and OPTIONS is supported with permissive headers to allow AJAX access.
| OPTIONS Request | All Responses |
|---|---|
% curl -i -X OPTIONS https://city-check.appspot.com/json HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Cache-Control: no-cache Access-Control-Allow-Origin: * Access-Control-Max-Age: 3628800 Access-Control-Allow-Methods: GET Access-Control-Allow-Headers: X-Requested-With Date: Tue, 09 Apr 2013 13:32:03 GMT Content-Length: 0 |
% curl -i https://city-check.appspot.com/json HTTP/1.1 200 OK Cache-Control: no-cache Access-Control-Allow-Origin: * Content-Type: application/json Vary: Accept-Encoding Date: Tue, 09 Apr 2013 13:32:46 GMT Transfer-Encoding: chunked |
A free public service of Ripe Apps. No warantees.