In version 2 we have introduced a number of new features and the response structure has changed slightly. Hence, all version 1 users are required to update their API call scripts. While version 2 is 100% backwards compatible, in order for you to take advantage of the new features you need to update your scripts.
There are 2 additional request parameters you need to send along with the IP address. While these 2 parameters are optional, if you don't pass them, you might as well not use version 2.
The request URL for version 2 is different:
http://api.locatorhq.com
| Parameter |
Description |
Format |
| API Key |
This is your standard API Key. |
key |
| IP Address |
Your IPv4 IP Address |
ip |
| Username |
Your username |
user |
| User Agent |
This is the server side user agent |
useragent |
| Referrer Source |
This is the source a user was referred from before entering your website. If blank, we'll consider that to be a direct visit to your website. |
referrer |
| Response Format |
Data is now returned in 3 formats. Unless you specify otherwise all data is returned in text format. Other formats accepted are XML and JSON. |
format |
The API returns data in the following format
| Response Param |
Description |
| countryCode |
ISO Country Code (e.g. NZ) |
| countryName |
Country Name: New Zealand |
| regionName |
For US/Canada this is the state value. For others this is the district/region value |
| cityName |
Auckland |
| cityLattitude |
Standard Lattitude |
| cityLongitude |
Standard Longitude |
| countryFlags |
Array type for flag PNG files. 128 px and 64 px high-res transparent PNG with hosted absolute URL. |
cityMap
|
http:// resource of a static image map (thanks to Google) |
| browserName |
e.g. Chrome |
| browserVersion |
e.g. 12 |
| browserFamily |
Webkit |
| browserCookies |
Enabled (yes/no) |
| browserJavascript |
Enabled (yes/no) |
| browserCSSVersion |
2.0 or 3.0 |
| osName |
e.g. Win7 or Mac OS X |
| deviceType |
iPhone 4 or Samsung Galaxy s II |
| entryKeyword |
The keyword used to enter your website (e.g. Google search organic referral) |
| entrySource |
The complete URL source of the referral |
| entryDomain |
The domain name of the referring source |
Try a sample API call and view source in
Plain Text: http://api.locatorhq.com/?user=<username>
&key=<apikey>
&ip=118.92.16.247&format=text
JSON -http://api.locatorhq.com/?user=<username>
&key=<apikey>
&ip=118.92.16.247&format=json
XML - http://api.locatorhq.com/?user=<username>
&key=<apikey>
&ip=118.92.16.247&format=xml |
