Documentation for the GeoIP Lookup and User Agent parser API

Userparser provides a fantastic IP address and user agent lookup API for free for 10,000 per month. You want more? you can upgrade at any time.

If you want to parse your user's user agent or/and Geolocation look up, we have a good solution for you you can Sign up and get your API key from your dashboard page then with that API key, you can parse any of your user's user agent and make geolocation lookup simply, and easily.

How can you integrate that with your system, Let us help you out step by step in this documentation.

In case if we left unanswered for any question you might ask please let us know it.

API Overview

After getting your uniquely generated hashed API key you can append and use it like this.

  
https://api.userparser.com/1.1/detect?api_key='YOUR_API_KEY';
  

Protect your API key: To prevent unauthorized use of your API key, please make sure to keep your API key private and safe from third parties. In case if you want to reset or change it you can do it in your dashboard page.

You can make either Geolocation Lookup only or User Agent Lookup or both at the same time.

Now get your users user agent data, if you use PHP you can get it by just looking up the HTTP_USER_AGENT header.

  
$user_agent = $_SERVER['HTTP_USER_AGENT'];
  

And Now get your users IP address, You can get it by just looking up the REMOTE_ADDR header.

  
$ip_address = $_SERVER['REMOTE_ADDR'];
  

Now to use all the above variables to make the whole new URL.

  
https://api.userparser.com/1.1/detect?ua=YOUR_USER_AGENT&ip=YOUR_IP_ADDRESS&api_key=YOUR_API_KEY
OR
https://api.userparser.com/1.1/detect?ua=$user_agent&ip=$ip_address&api_key=6H8xxxxxxxxxxxxxxxxxxx4B7
  

Now you can make a CURL request.

  
$ curl "https://api.userparser.com/1.1/detect?ua=YOUR_USER_AGENT&ip=YOUR_IP_ADDRESS&api_key=YOUR_API_KEY"
  

API Response

Our API response is either through JSON or XML as you want.
We've an optional parameter called format which uses to choose either JSON or XML response. If you don't specify this parameter the API response will be in JSON format (defualt API response is JSON).

JSON Response

  
{
    "info": {
        "status": "success",
        "message": "The user agent was parsed and IP lookup was complete successfully.",
        "ua": "Mozilla/5.0 (Linux; Android 11; SM-A505F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.101 Mobile Safari/537.36",
        "ip": "80.207.161.200"
    },
    "browser": {
        "name": "Chrome",
        "version": "98",
        "fullVersion": "98.0.4758.101",
        "engine": "Blink"
    },
    "operatingSystem": {
        "name": "Android",
        "version": "11"
    },
    "device": {
        "name": "Samsung Galaxy A50",
        "type": "Smartphone",
        "brand": "Samsung",
        "screenResolutionWidth": "1080px",
        "screenResolutionHeight": "2340px",
        "viewportWidth": "412px",
        "viewportHeight": "756px",
        "language": null,
        "isTouchScreen": true,
        "isMobile": true
    },
    "crawler": {
        "isCrawler": false,
        "name": null,
        "owner": null,
        "category": null,
        "url": null,
        "lastSeen": null
    },
        "location": {
        "countryName": "Italy",
        "countryCode2": "IT",
        "countryCode3": "ITA",
        "capitalCity": "Rome",
        "continentName": "Europe",
        "continentCode": "EU",
        "callingCode": "+39",
        "currencyCode": "EUR"
    }
}
  

XML Response

  
<response>
<info>
<status>success</status>
<message>The user agent was parsed and ip lookup was complete successfully.</message>
<ua>Mozilla/5.0 (Linux; Android 11; SM-A505F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/98.0.4758.101 Mobile Safari/537.36</ua>
<ip>80.207.161.200</ip>
</info>
<browser>
<name>Chrome</name>
<version>98</version>
<fullVersion>98.0.4758.101</fullVersion>
<engine>Blink</engine>
</browser>
<operatingSystem>
<name>Android</name>
<version>11</version>
</operatingSystem>
<device>
<name>Samsung Galaxy A50</name>
<type>Smartphone</type>
<brand>Samsung</brand>
<screenResolutionWidth>1080px</screenResolutionWidth>
<screenResolutionHeight>2340px</screenResolutionHeight>
<viewportScreenWidth>412px</viewportScreenWidth>
<viewportScreenHeight>756px</viewportScreenHeight>
<language/>
<isTouchScreen>1</isTouchScreen>
<isMobile>1</isMobile>
</device>
<crawler>
<isCrawler/>
<name/>
<owner/>
<category/>
<url/>
<lastSeen/>
</crawler>
<location>
<countryName>Italy</countryName>
<countryCode2>IT</countryCode2>
<countryCode3>ITA</countryCode3>
<capitalCity>Rome</capitalCity>
<continentName>Europe</continentName>
<continentCode>EU</continentCode>
<callingCode>39</callingCode>
<currencyCode>EUR</currencyCode>
</location>
</response>
  

API Error handler

Whenever the API failed to process the request, it gives the reason of the failure in the status and message of the API response.

The response in the status name has an error value in error response.

The response in the message name has the reason of the error response.

General speaking whenever there is error in the request process the status will be return error value. And the message name will have the error reason.

API Error example

  
{
    "info": {
        "status": "error",
        "message": "Invalid API KEY, please get your valid API key from here [ https://www.userparser.com/dashboard/ ]."
    }
}
 

API Response Objects

Based on your request parameters and our API response data there are more than 32 API response objects.

API HTTP GET or POST Request Parameters

The API have two required parameters and one another optional parameter.

NOTE: You can send either user agent or IP address or both as you want.

Code Examples

You can use our API service in any programming language you want. Some of them

PHP

  
$json_url = "https://api.userparser.com/1.1/detect?ua=YOUR_USER_AGENT&ip=YOUR_USERS_IP_ADDRESS&api_key=YOUR_API_KEY";
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $json_url);
$json_data = curl_exec($ch);
curl_close($ch);
$json_result = json_decode($json_data);

if($json_result->browser->name == "Chrome"){
    echo "Its a Chrome browser.";
}
 

Before sending your user agent to the API, use the built-in PHP function urlencode().

urlencode() is a function in PHP that is used to encode a string into a URL-friendly format. It converts special characters, such as spaces and punctuation marks, into their respective hexadecimal values.

You can use it like this

  
$urlencoded_user_agent = urlencode($user_agent); // With encoded url like this, your request is safe.
 

Python

  
import requests

json_data = requests.get('https://api.userparser.com/1.1/detect?ua=YOUR_USER_AGENT&ip=YOUR_USERS_IP_ADDRESS&api_key=YOUR_API_KEY')

if json_data.json()['browser']['name'] == 'Chrome':
  print ('Its a Chrome browser.');
  

jQuery

 
  $.ajax({
  url: 'https://api.userparser.com/1.1/detect',
  type: 'POST',
  dataType: 'JSON',
  data: {
     api_key: 'YOUR_API_KEY',
     ua: 'YOUR_USER_AGENT',
     ip:'YOUR_USERS_IP_ADDRESS'
  },
  success: function(json) {
    if (json.device && json.device.type == 'Smartphone') {
      console.log("It's a Smartphone.");
    }
  }
});
  

If you've question or need technical support please contact us directly.

Happy coding 😊