GeoIPs API Guide

Our API provides IP related information using a REST interface that returns the following data:

  • hostname
  • owner
  • continent name, continent code
  • country name, country code
  • region name, region code
  • county name
  • city name
  • latitude, longitude
  • timezone
  • official language
  • currency

Request

Calling the GeoIPs API is easy and intuitive. Make the request by appending valid parameters for your query:

http://api.geoips.com/ip/«ip_address»/key/«api_key»/output/«format»/timezone/«bool»/hostname/«bool»/language/«bool»/currency/«bool»

the parameters can be specified in any order inside URL

Parameters

Parameter Required Default Value Description
ip no client IP address IP address
key yes empty API key provided for registered application
output no XML specifies the format for responses: XML, JSON, RAW
timezone no false specifies the timezone for responses: true, false
hostname no false specifies the hostname for responses: true, false
language no false specifies the official language for responses: true, false
currency no false specifies the currency for responses: true, false

In order to obtain a valid API key for your application or website, please register for a GeoIPs user account.

Response

Element Description
ip referenced IP address
hostname hostname of the supplied IP address
owner owner of the suplied IP address
continent_name continent name
continent_code continent code
country_name ISO-3166 country name
country_code ISO-3166 two-letter country code
region_name region name
region_code region code
county_name county name
city_name city name
latitude latitude of the identified location, with positive numbers representing North and negative numbers representing South
longitude longitude of the identified location, with positive numbers representing East and negative numbers representing West
timezone timezone

By default, GeoIPs API sends responses in structured XML data format. You can also request the response in JSON data format or plain text (RAW).

Sample XML Response

<response>
<status>Propper Request</status>
<message>Success</message>
<notes>The following results has been returned</notes>
<code>200_1</code>
<location>
<ip>8.8.8.8</ip>
<owner>LEVEL 3 COMMUNICATIONS INC</owner>
<continent_name>NORTH AMERICA</continent_name>
<continent_code>NA</continent_code>
<country_name>UNITED STATES</country_name>
<country_code>US</country_code>
<region_name>CALIFORNIA</region_name>
<region_code>CA</region_code>
<county_name>SANTA CLARA</county_name>
<city_name>MOUNTAIN VIEW</city_name>
<latitude>37.3801</latitude>
<longitude>-122.0865</longitude>
<timezone>PST</timezone>
</location>
<languages>
<language>
<alpha2_code>EN</alpha2_code>
<alpha3_code>ENG</alpha3_code>
<language_name>ENGLISH</language_name>
<native_name>ENGLISH</native_name>
</language>
</languages>
<currencies>
<currency>
<alpha_code>USD</alpha_code>
<numeric_code>840</numeric_code>
<currency_name>US DOLLAR</currency_name>
<currency_symbol>$</currency_symbol>
<fractional_unit>CENT</fractional_unit>
</currency>
</currencies>
<unit_test>
<elapsed_time>0.0609</elapsed_time>
<memory_usage>0.76MB</memory_usage>
</unit_test>
</response>

Sample JSON Response

{
"response": {
"status": "Propper Request",
"message": "Success",
"notes": "The following results has been returned",
"code": "200_1",
"location": {
"ip": "8.8.8.8",
"owner": "LEVEL 3 COMMUNICATIONS INC",
"continent_name": "NORTH AMERICA",
"continent_code": "NA",
"country_name": "UNITED STATES",
"country_code": "US",
"region_name": "CALIFORNIA",
"region_code": "CA",
"county_name": "SANTA CLARA",
"city_name": "MOUNTAIN VIEW",
"latitude": "37.3801",
"longitude": "-122.0865",
"timezone": "PST"
},
"languages": {
"language": [
{
"alpha2_code": "EN",
"alpha3_code": "ENG",
"language_name": "ENGLISH",
"native_name": "ENGLISH"
}
]
},
"currencies": {
"currency": [
{
"alpha_code": "USD",
"numeric_code": "840",
"currency_name": "US DOLLAR",
"currency_symbol": "$",
"fractional_unit": "CENT"
}
]
},
"unit_test": {
"elapsed_time": "0.0609",
"memory_usage": "0.76MB"
}
}
}

Sample RAW Response

Propper Request,Success,The following results has been returned,200_1, 8.8.8.8,LEVEL 3 COMMUNICATIONS INC,NORTH AMERICA,NA,UNITED STATES,US,CALIFORNIA,CA,SANTA CLARA,MOUNTAIN VIEW,37.3801,-122.0865,PST, languages,1,EN,ENG,ENGLISH,ENGLISH, currencies,1,USD,840,US DOLLAR,$,CENT, unit_test,0.609,0.76MB

Code Status Message Description
200_1 Propper Request Success The following results has been returned.
200_2 Propper Request Not Found No result set has been returned.

Error Messages

If a request fails, the GeoIPs API returns an error message. By default, the message is returned as structured XML, but JSON and RAW messages are also available.

<error>
<status>status</status>
<message>message</message>
<notes>notes</notes>
<code>code</code>
<unit_test>
<elapsed_time>time</elapsed_time>
<memory_usage>memory</memory_usage>
</unit_test>
</error>

Code Status Message Description
400_1 Bad Request Error in the URI The API call should include an API key parameter.
400_2 Bad Request Error in the URI The API call should include a valid IP address.
403_1 Forbidden Not Authorized The API key associated with your request was not recognized.
403_2 Forbidden Account Inactive The API key has not been approved or has been disabled.
403_3 Forbidden Limit Exceeded The service you have requested is over capacity.

Pricing Plans

Choose the right Plan for you

The GeoIPs IP Intelligence Service provides a variety of pricing plans to meet your needs: Developer, Basic, Professional, Enterprise. For more details, please check our Pricing Plans.