Overview of our IP Address Geolocation Online Service
The IP-GeoLoc™ IP Address Geolocation Online Service is a hosted Web Service that allows instant identification of your online visitor's geographical location by using his IP address in real time. Your web site communicates with our cloud-based service, sends your visitor's IP address, and receives its geographic information such as the Continent, Country Code, Country Name, Region (State, County, Province, Region, Territory, District, etc), City, Postal/ZIP Code, Metro Code, Area Code, Latitude, Longitude, Internet Service Provider (ISP) and Organization. This IP address geolocation response is returned to your web site in less than 1/20th of a second in XML or JSON format (you can see an example of these formats here). Your code then obtains the IP address geolocation information from this response by simply using string manipulation, or by parsing the XML tags or JSON objects using any parsing component (there are many of such components available for every modern programming language, all of them for free).
How our IP Address Geolocation Online Service works
It is very simple. Your web site makes a call to our IP address geolocation service using either the HTTP "GET" or "POST" methods.
If you choose to use the HTTP "GET" method you should use the following URL:
http://api.apigurus.com/iplocation/v1.8/locateip?key={your "Service Access Key"}&ip={the visitor's IP address}&format={XML/JSON} [&callback={your JavaScript function name}] [&compact={Y/N}]
Example: http://api.apigurus.com/iplocation/v1.8/locateip?key=ExampleKey123456789&ip=3.143.0.122&format=XML
Alternatively, the "ip" parameter may contain "local-ip" as a static value instead of the visitor's IP address. In such case, the IP address of the host from which our service is invoked will be geolocated. This is particularly useful when our service is invoked from a desktop application that needs to geolocate the IP address of the host from which it is being executed. It is also very useful when our service is invoked by a javascript code that is executed in the visitor's browser (instead of by the web server in which the site resides).
The format parameter specifies the data format for the response (XML or JSON). We also support JSON with Padding (JSONP), which allows callers to insert a dynamic script element and requires a user-specified function name. If you have specified the format as JSON, you can request that our service return the JSON data wrapped in a specified function name. To do so, use the "callback" parameter in the form "callback={your JavaScript function name}".
By default, the answers in XML and JSON come formated with indentations, spacings and line breaks. This facilitates its reading and understanding for humans. However, our service will be ultimately used by automated processes through parsing. To facilitate this process and abreviate the size of the response, it is possible to obviate the formating elements. This can be achieved using the "compact" parameter, in the form "compact=Y".
You can use the HTTP "POST" method instead of the HTTP "GET" method. To do so, just use the URL up to the "?" character and send the required data inside the message body. You can also use the HTTPS (HTTP secure) protocol instead of the HTTP protocol. Just start the URL with "https://https-api" instead of with "http://api".
The "Service Access Key" is a value that identifies your geolocation service license in our system, either as a trial user or as a subscribed user. To get your own Service Access Key, please register, then sign in, and then get your Free Trial License or subscribe to our IP address geolocation service.
The HTTP "GET" or HTTP "POST" methods are programmatically performed from your website in real time, so you must have access to your website's source code to extend it. All modern languages (such as Java/JSP, ASP, PHP, C#, Visual Basic, C, C++, JavaScript and others) include libraries that implement the HTTP protocol, and allow you to invoke our service with just a few lines of code. All web programming languages also allow you to obtain the visitor's IP address with just a few lines of code.
Please notice the "/v1.8/" part in the URL, which indicates the latest version of our API. This is the version you should use if you are about to start using our service. For further information about our versioning system, please check its Changelog and FAQ.
Features of our IP Address Geolocation Online Service
- Highly Accurate: Our IP mapping technology covers 99.99% of the 4,294,967,296 IPv4 addresses around the world. Our IP address geolocation database is continuously updated.
- Fast, in Real-Time: Our IP address geolocation service returns a response to your web site in less than 1/20th of a second.
- Generous Rates: If you use just one license, you can make up to 300 queries/minute yet not exceed 100,000 queries/day. These rates are applicable to every edition of the service (Basic, Standard and Professional), and to paid licenses as well as free trial licenses. Should you need a higher rate, you could easily extend that ceiling by purchasing additional licenses.
- Affordable: The monthly subscription fee can be as low as US$ 14.4 (for the Basic Edition, paying for 12 months in advance).
- No Setup Fees: Pay as you go. You can start paying for just one month of service, with no setup fees.
- Several Editions: You can choose from the Basic, Standard and Professional editions, depending on your information needs.
- Free Trial License: Ask for a free trial license to evaluate our IP address geolocation service before you pay for a subscription.
- Web Service: No software to buy and install in your server. No databases to install that would require frequent manual updates.
- Easy to Integrate: You can invoke our IP address geolocation service from your web site with just a few lines of code. All modern programming languages are supported (Java/JSP, ASP, PHP, C#, Visual Basic, C, C++, JavaScript, etc).
- 99.995% Availability: Designed to achieve a 99.995% availability, which is equivalent to 26 minutes of downtime per year at the most, considering both hardware/software failures and planned maintenances.
- The Best Support: Our fast and friendly customer support staff will be more than happy to assist you before and after you subscribe to our service.
Things your web site can do with our IP Address Geolocation Online Service
|
|
Editions, Plans and Pricing of our IP Address Geolocation Online Service
All license types displayed in the following table have some limits regarding the rate at which the geolocation service can be used.
If you use just one license, you can make up to 300 queries/minute yet not exceed 100,000 queries/day. These rates are applicable to every edition of the service (Basic, Standard and Professional), and to paid licenses as well as free trial licenses. Should you need a higher rate, you could easily extend that ceiling by purchasing additional licenses. Doing so will have a multiplicative effect on such limits, therefore allowing you to make "x" times more queries per minute and day. For instance, if you were to purchase an additional license for a total of two, you would be able to make up to 600 queries/minute yet not exceed 200,000 queries/day. Once you have purchased multiple licenses, ask us to accrue your total rate to be used with just one of them.
If your rate limit is exceeded, you will receive a response with a HTTP/1.1 status code 429 ("Too Many Requests"), instead of the HTTP/1.1 status code 200 ("OK") which is the standard status code for successful HTTP requests. The response body will be empty (no XML, JSON or HTML content). This status is temporary and will be removed when usage of our service is back within your allowed rates (queries per minute and day). Your software should be able to detect the status code 429 when/if received and interpret it as an excess activity triggered by your use of our service as opposed to a service failure.
Please let us know if you would like any additional information about multiple license usage.
|
||||||||||||||||||||||||||||||||||||||||
Output Fields of our IP Address Geolocation Online Service (Editions Comparison)
| Output Field | Format | Description | Basic Edition |
Standard Edition |
Pro Edition |
|---|---|---|---|---|---|
| continent_code | char(2) |
Continent two-letter code. AF=Africa, AN=Antarctica, AS=Asia, EU=Europa, NA=North America, OC=Oceania, SA=South America. |
 |
|
|
| continent_name | varchar(15) |
Continent name. "Africa", "Antarctica", "Asia", "Europa", "North America", "Oceania" or "South America". |
|
|
|
| country_code_iso3166alpha2 | char(2) |
Country code (ISO 3166-1 Alpha-2 standard, two-letter code). More information |
|
|
|
| country_code_iso3166alpha3 | char(3) |
Country code (ISO 3166-1 Alpha-3 standard, three-letter code). More information |
|
|
|
| country_code_iso3166numeric | char(3) |
Country code (ISO 3166-1 Numeric standard, three-digit code). More information |
|
|
|
| country_code_fips10-4 | char(2) |
Country code (FIPS 10-4 standard, two-letter code). More information |
|
|
|
| country_name | varchar(50) |
Country name (ISO 3166-1 standard). More information |
|
|
|
| region_code | varchar(4) |
Region code ("Region" means "State" in the USA, "County" in the UK, "Province/Territory" in Canada, "Region" in Italy, etc). For the USA and Canada, it uses the ISO 3166-2 standard with the addition of some entries for the US Armed Forces (more information). Outside of the USA and Canada, it uses the FIPS 10-4 standard (more information). |
|
|
|
| region_name | varchar(100) |
Region name ("Region" means "State" in the USA, "County" in the UK, "Province/Territory" in Canada, "Region" in Italy, etc). For the USA and Canada, it uses the ISO 3166-2 standard with the addition of some entries for the US Armed Forces (more information). Outside of the USA and Canada, it uses the FIPS 10-4 standard (more information). |
|
|
|
| city | varchar(100) | Name of city (or town), in ISO-8859-1 encoding. | |
|
|
| postal_code | varchar(6) |
Postal code (only available for the USA and Canada). More information |
|
|
|
| metro_code | char(3) |
US metropolitan region code ("Metro Code"). Only available for the USA. More information |
|
|
|
| area_code | char(3) | Area code, three-digit telephone prefix (only available for the USA). | |
|
|
| latitude | decimal(8,4) |
Depending on the most specific geographical area to which we were able to relate an IP address, this field would bring the latitude of the center of the zip code, city, region or country where such address was located in that particular order. (i.e. latitude of the center of the region will be provided if the IP address could be related to a region, but not to a specific zip code or city, which are more specific). |
|
||
| longitude | decimal(8,4) |
Depending on the most specific geographical area to which we were able to relate an IP address, this field would bring the longitude of the center of the zip code, city, region or country where such address was located in that particular order. (i.e. longitude of the center of the region will be provided if the IP address could be related to a region, but not to a specific zip code or city, which are more specific). |
|
||
| isp | varchar(100) |
Internet Service Provider (ISP) that owns the IP address. More information |
|
||
| organization | varchar(100) |
Organization the IP address is assigned to. More information |
|
||
| ip_address | varchar(15) | IP address supplied as input to the service. | |
|
|
| query_status_code | varchar(50) |
"OK" if the query was correctly invoked, otherwise an error code. Possible values |
|
|
|
| query_status_description | varchar(250) |
Explains the code received in query_status_code. More information |
|
|
|
| Live Demo |
|
||||
A "-" character (ASCII Dec 45/Hex 0x2D, Unicode U+002D) is returned by some fields when no value is available.
Input Parameters to call our IP Address Geolocation Online Service
| Input Parameter | Description |
|---|---|
| ip | Your visitor's IP address. |
| key | The Service Access Key that identifies your license. |
| format | Specifies the data format for the response. Possible values: "XML" , "JSON". |
| callback | Specifies your JavaScript function name (for JSONP). |
| compact | Used to remove indentations, spacings and line breaks. Possible values: "Y" , "N". |