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

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»

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

The parameters can be specified in any order inside URL.

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

Response

Default Value
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

ISO: International Organization for Standardization

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>Success</status>
	<ip>66.147.244.214</ip>
	<hostname>box714.bluehost.com</hostname>
	<owner>BLUEHOST 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>UTAH</region_name>
	<region_code>UT</region_code>
	<county_name>UTAH</county_name>
	<city_name>PROVO</city_name>
	<latitude>40.3402</latitude>
	<longitude>-111.6073</longitude>
	<timezone>MST</timezone>
</response>

Sample JSON Response

{
	"status" : "Success",
	"ip" : "66.147.244.214",
	"hostname" : "box714.bluehost.com",
	"owner" : "BLUEHOST INC.",
	"continent_name" : "NORTH AMERICA",
	"continent_code" : "NA",
	"country_name" : "UNITED STATES",
	"country_code" : "US",
	"region_name" : "UTAH",
	"region_code" : "UT",
	"county_name" : "UTAH",
	"city_name" : "PROVO",
	"latitude" : "40.3402",
	"longitude" : "-111.6073",
	"timezone" : "MST",
}

Sample RAW Response

Success,66.147.244.214,box714.bluehost.com,BLUEHOST INC.,NORTH AMERICA,NA,UNITED STATES,US,UTAH,UT,UTAH,PROVO,40.3402,-111.6073,MST

Error Messages

If a request fails, the GeoIPs API returns a 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>
</error>
Status
Message
Description
Bad Request
Error in the URI
The API call should include a valid API key parameter.
Bad Request
IP Not Found
The API call should include a valid IP address.
Forbidden
Not Authorized
The API key associated with your request was not recognized.
Forbidden
Account Inactive
The API key has not been approved or has been disabled.
Forbidden
Limit Exceeded
The service you have requested is over capacity.

Contact

Update & Correction

Update & Correction Suggestions about update or correction? Let us know using the following email address and we will contact you in the next few days.