* βeta
World Countries API
World Countries Information and ip geocoding RESTful Web services API
World Countries Information and ip geocoding RESTful Web services API
Best Practices while using “World Countries” information and geolocation API service:
Service Description:
Geognos provides this web service as an interface for requesting geocoding and country information from our services for use within your applications.
This web services responds to HTTP Get requests to specific URLs (end points) by returning data as either json, jsonp, XML or HTML for parsing and/or processing by your application.
A typical Web Service request is of the following form:
http://www.geognos.com/api/en/countries/service_name/counry_code_or_ip.ouput_format
where:
- service_name indicates the particular service requested as follows:
- “info”:outputs generic information about the country specified.
- “flag”:outputs the flag of the country specified.
- counry_code_or_ip which can be:
- counry_code_or_ip can indicate:
- a capitalized ISO 3166-1-alpha-2 country code i.e. "US" for receiving general information about the particular country. For a list of all World Countries codes you can look here: World Country codes.
- or the word “all” for receiving results for all world countries.
- or an ip address i.e. 204.193.118.11 for receiving the the ISO country code of the country that this ip belongs (* see geo-coding) when service_name="cc" or the information for that particular country when service_name="info".
- or “_” (single underscore character) a special case of the above in which the ip is not defined in the request but instead it is derived from request header.
- output_format indicates the response format and can be one of the following:
- “json”
- “jsonp” the same as above enclosed in “callback (json)” for use by java script applications.
- “xml” (not implemented yet)
- “html” it is only available with "info" service and outputs a well formatted html table ready to be included in your application. You can use the class names included in the html tags to format the output with css.
- “png” is only available with the “flag” service and outputs a png image.
- “StatusCode”: An HTTP response code (i.e. 200 for a successful request) - Applications should check this code before proceeding with processing the response.
- “StatusMsg”: A message associated with the response (i.e. “OK”,for successful request)
- “Results”: Actual results (depending on the service some result fields can be missing or null):
- "Name" is the Name of the country
- “SeqID” a sequence Id for this country - can be useful in creating sprite images of flags.
- "TelPref" is the international telephone code prefix for that country.
- “CountryCodes” a list of country specific codes:
- “iso2” the ISO 3166-1-alpha-2 character code
- “iso3” the ISO 3 character code
- “isoN” the ISO Numeric code
- “FIPS” the FIPS code
- “tld” the Inernet Top Level Domain code
- “GeoPt” Center of Country [latitude, longitude]
- “Capital” a list with info about country’s capital:
- “Name” Name of the Capital
- “TD” Time Difference from GMT (hours)
- “DLST” Day Light saving Time (hours)
- “GeoPt” Geographical Coordinates [latitude, longitude]
- “GeoRectangle” a list of the Geographical Coordinates of country’s bounding rectangle:
- “West”
- “North”
- “South”
- “East”
- “CountryInfo” a URL in geognos domain where farther information about this country is provided.
- http://www.geognos.com/api/en/countries/info/FR.json
- http://www.geognos.com/api/en/countries/info/FR.jsonp
- http://www.geognos.com/api/en/countries/info/GR.html
- http://www.geognos.com/api/en/countries/flag/GR.png
- http://www.geognos.com/api/en/countries/info/204.193.118.11.json
- http://www.geognos.com/api/en/countries/info/_.json
- http://www.geognos.com/api/en/countries/info/all.json
- http://www.geognos.com/api/en/countries/cc/_.json
- http://www.geognos.com/api/en/countries/info/all.html
- geognos.com general Terms Of Service and privacy policy are applicable to users of this API service.
- This service is free for use strictly on public-facing, non-password protected Web sites / applications.
- This Service can be only used in production from registered applications and after a confirmation email (OK) is sent back to you in reply to your submission of the Registration form. No API/developer key is required.
- Access is granted on a “first come first served” basis except that registration requests for applications running on Google’s App Engine© receive a priority when we process registration requests.
- An attribution link to: http://www.geognos.com/ must be provided on any site / application using this service.
Geo-location is not an exact science so the accuracy of the results can not be guaranteed.
Our service provides country level results only.
This service works by comparing an ip to an app Engine hosted database of ip blocks and routing tables which is updated daily from data files provided by RIRS around the world. Some adjustments to compensate for various factors can be applied to those rough data. The service in no way depends on or uses any other third party service, API, or database.
For the time been it only handles ipv4 addresses but we do plan to extend it for handling ipv6.
- Client originated requests from user pages : 1000 Maximum number of requests per day per ip.
- Server originated requests: Maximum 12000 requests per day per server domain or app id for (Google Application Engine© based requests).
- Requests Rate limit: Maximum 5 requests per ip per second.
- Client originated (i.e. requests from JS running in a browser) that require a geo-coding operation as described in § 2.c, 2.d above will not be granted. For this kind of service you can look at alternative APIs as Googles js geocoding API.
- A limited number of API requests (300 per day) is available to any application - client for testing purposes, no registration is needed for testing.
- Application quotas are reset at midnight, Pacific Time.
These limits are enforced to prevent abuse of the service, and may be changed in the future without notice. If you exceed these limits or otherwise abuse the service, this API may stop working for you.
You can request an increase on a particular limit by contacting us, but we can’t guarantee that the increase will be granted.
Best Practices while using “World Countries” information and geolocation API service:
- Use cookies and/or session variables to store results of the service when possible so you can avoid a duplicated request on behalf of same client later.
- For the Country information service you can avoid repeated requests for individual countries if you get the information for all countries using “all” as described in § 2.b, save a copy of the results on your server and use this copy to provide information for a particular country (example #8).
- For content heavy requests custom clients can force content to be compressed by specifying both Accept-Encoding and User-Agent headers with a value of "gzip".
- A png image of all flags arranged vertically is provided in:http://www.geognos.com/media/flags/world-countries-flags-80X40.png and http://www.geognos.com/media/flags/world-countries-flags-32X16.pngThese images can be used for serving individual flags as image sprites by offsetting vertical position using css sprites techniques. Offset values can be calculated by using the “IdSeq” field of the “info” request and image dimensions. This is the most efficient way for displaying lots of flags. For an example of using sprites you can look at the source code of the following page: http://www.geognos.com/api/en/countries/info/IT.html
- Version 1.0.1 - Date:Dec 22 24:00 GMT
“GeoLat” Center of Country Coordinates Latitude and “GeoLon” Center of Country Coordinates Longitude, have been replaced by “GeoPt” Center of Country [latitude, longitude]. We have changed this in order for Json output to be more readable and avoid ambiguities.
- Why you provide this service?
- Short answer is: there is no specific reason. We just developed the service for use in our own application and thought it is good idea to share it with the community of App Engine developers since the problem of providing geocoding and country information are common in many applications. We are also ready to open source the code provided we find some more volunteers ready to help with this task.
- Why applications running on Google’s App Engine receive a preferable treatment?
- Because we can process efficiently only a limited number of requests.
Applications based on App Engine have an inherent problem of using similar third party API’s with quota limits based on ip addresses since all of those are served from the same block of ips allocated by Google© and therefore have to share those quotas with other applications hosted on App Engine and using the same service (read here and here ), so our priority is to help solving this problem. - Since this service also runs on App Engine, it minimizes by quite a margin the probability of having one more “possible point of failure” for applications using it, as any App Engine major disruption will probably affect both this service and any application using it at that time.
- For the same reason we expect reduced latency times when this service is called from applications within Google’s© infrastructure.
- Why I must register my application?
- Registering helps us with capacity planing, also we need an email address just in case we need to communicate with service users.
- What you mean by attribution link?
- Any link from the site using the API to www.geognos.com i.e.:
<a href="http://www.geognos.com/geo/en/cc/ad.html" title="World Countries : Andorra" target="_blank">World Countries : Andorra </a>
- Can I simply hotlink to a flag image?
(i.e : <img src="http://www.geognos.com/api/en/countries/flag/AD.png">)
- Yes you can provided you include an attribution link in your site as described in TOS.
