Quova On Demand REST API

Quova GeoPoint provides the geographic location for any given Internet Protocol (IP) address in the public address space. The GeoPoint-REST API is a standard REST-based service that returns geographic metadata over HTTP for a given IP address. The location information includes:

City, state, country, region, and continent
Longitude and latitude
Designated Market Area and Metropolitan Statistical Area
Network information, including type and speed

This document describes the details of the geolocation and network data delivered by GeoPoint for each routable IP address.

HTTP Request
1. Code Samples
  1. Python
  2. Java
  3. Ruby
  4. C#
  5. PHP
XML Response
1. Sample
2. Reference
  1. IpInfo
  2. Location
  3. City
  4. Coordinates
  5. Continent
  6. Country
  7. DMA
  8. MSA
  9. Network
  10. Region
  11. State
  12. Constants

HTTP Request

The GeoPoint-REST API is accessed by making an HTTP request to Quova.com. You must first provide valid credentials for authorization, and then make the HTTP request, passing in the IP address at the end of this URL:

https://webservices.quova.com/ipinfo/

Consider the following simple example in Python. The first part handles the authentication through user credentials, following a standard Basic Authentication scheme. The second part makes the request, returning XML.

import urllib2 
# Create user credentials
s_user = 'Your Quova web services username' 
s_pass = 'Your Quova web services password' 
password_manager = urllib2.HTTPPasswordMgrWithDefaultRealm() 
password_manager.add_password(  None, 'https://webservices.quova.com/', s_user, s_pass )
auth_handler = urllib2.HTTPBasicAuthHandler(password_manager) 

# Retrieve the XML
opener = urllib2.build_opener(auth_handler) 
xml = urllib2.urlopen('https://webservices.quova.com/ipinfo/4.2.2.2').read()

Assuming your credentials are valid, this request would return an XML payload into a variable named xml.

Note: This is sample-level code, unsuitable for production environments. Robust usage would also include error handling to catch situations where the request fails at the HTTP level.

Code Samples

Code samples in Python, Java, Ruby, and C# are provided below. In each case, they retrieve XML for the IP address 4.2.2.2 using credentials of username='username' and password='password', and then they display the returned XML.

Python

The following is a simple example in Python that uses the HTTPPasswordMgrWithDefaultRealm and HTTPBasicAuthHandler functions from the urllib2 library.

s_user = 'username'
s_pass = 'password'<br /> <br />password_manager = urllib2.HTTP<br />PasswordMgrWithDefaultRealm()<br />password_manager.add_password(<br />	None, 'https://webservices.quova.com/', s_user, s_pass<br />)<br />auth_handler = urllib2.HTTPBasic<br />AuthHandler(password_manager)<br />opener = urllib2.build_opener(auth_handler)xml = urllib2.urlopen('https://webservices.quova.com/ipinfo/4.2.2.2').read()<br /><br />print xml

If you prefer to handle authentication more directly, then the following Python example with exception handling may be more appropriate.

import urllib2
import sys
import re
import base64
from urlparse import urlparse

url = 'https://webservices.quova.com/ipinfo/4.2.2.2'; 

# Replace 'username' and 'password' with
# your Quova GeoPoint-REST username and password

username = 'username'
password = 'password' 
req = urllib2.Request(url)

try:
    # Try to open the request. This should fail because we have not
    # passed in credentials for authentication.
    handle = urllib2.urlopen(req)
except IOError, e:
    # We are hoping that opening the request will fail, and that
    # this code will be called.
    pass
else:
    # If no exception is thrown, then the page isn't protected.
    # In this case, we don't want the result.
    print "This page isn't protected by authentication."
    sys.exit(1)

# Make sure the exception is a 401 exception. 
If not, then exit.if not hasattr(e, 'code') or e.code != 401:
    print "This page isn't protected by authentication."
    print "But the request failed for another reason."
    sys.exit(1)

# Add authentication
base64string = base64.encodestring(
                '%s:%s' % (username, password))[:-1]
authheader =  "Basic %s" % base64string
req.add_header("Authorization", authheader) 

# Try opening the request againtry:
    handle = urllib2.urlopen(req)
except IOError, e:
    # This time, the request will only fail if username/password is incorrect.
    print "It appears that the username or password is wrong."
    sys.exit(1)
data = handle.read()

print data

Note: These Python examples are based on code from the Basic Authentication in Python article at http://www.voidspace.org.uk/.

Java

The following Java sample illustrates how to execute a web service request for Quova via an HTTP GET. It relies on the HttpComponents package from the Apache Software Foundation.

/**
 * Quova GeoPoint-REST Web Services
 *
 * @author www.quova.com
 * Copyright 2010 Quova, Inc.
 *
 * This example illustrates how to execute a web service request via HTTP GET.
 */  

import java.io.*;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient; 

public class QuovaRestClient {
    public static void main(String[] args) {
        String url = "https://webservices.quova.com/ipinfo/4.2.2.2";
        String username = "username";
        String password = "password";
        String host = "webservices.quova.com";
    DefaultHttpClient httpclient = new DefaultHttpClient(); 

    // Set credentials
    httpclient.getCredentialsProvider().setCredentials(
        new AuthScope(host, 443),
        new UsernamePasswordCredentials(username, password)); 

    // Create an HTTP GET request
    HttpGet httpget = new HttpGet(url); 

    // Execute the request
    System.out.println("executing request: " + httpget.getRequestLine());
    HttpResponse response = null;
        try {
            response = httpclient.execute(httpget);
        } catch (ClientProtocolException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    HttpEntity entity = response.getEntity();
 

    // Print the response
    System.out.println("----------------------------------------");
    System.out.println(response.getStatusLine());
    if (entity != null) {
        System.out.println("Response content length: " + entity.getContentLength());
    }
    if (entity != null) {
        try {
            InputStream inputStream = entity.getContent();
 
            // Process the response from Quova GeoPoint-REST
            BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(inputStream));
            String line;
            while ((line = bufferedReader.readLine()) != null) {
                System.out.println(line);
            }
            bufferedReader.close();
                } catch (IOException e) {
                    e.printStackTrace();
                }
    }
 
    // When HttpClient instance is no longer needed,
    // shut down the connection manager to ensure
    // immediate deallocation of all system resources.
    httpclient.getConnectionManager().shutdown();
    }
}

Ruby

The following Ruby sample uses Net::HTTP.

require 'net/https'
http = Net::HTTP.new('webservices.quova.com', 443)
http.use_ssl = true
http.start do |http|
   req = Net::HTTP::Get.new('/ipinfo/4.2.2.2')

   # Make an HTTP basic authorization by passing the
   # username and password.
   req.basic_auth 'username', 'password'

   resp, data = http.request(req)
   print data
end

Note: This Ruby example is based on code from the article Make Yahoo! Web Service REST calls with Ruby.

C#

The following C# sample uses HttpWebRequest and HttpWebResponse.

using System;
using System.Net;
using System.IO;

namespace ConsoleApp{
    class Program
    {
        static void Main(string[] args)
        {
            string url = "https://webservices.quova.com/ipinfo/4.2.2.2";
            string username = "username";
            string password = "password";
            // Create the web request
            HttpWebRequest request = WebRequest.Create(url) as HttpWebRequest;

             // Add authentication to request
             request.Credentials = new NetworkCredential(username, password);
             // Get response
             using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
            {
                // Get the response stream
                StreamReader reader = new StreamReader(response.GetResponseStream());

                // Write response to the console
                Console.WriteLine(reader.ReadToEnd());
            }
        }
    }
}

PHP

The following PHP sample uses curl and obtains an XML response.

function quovaXML($ip = '') {

$quovaUser = 'username';
$quovaPass = 'password';
if (empty($ip)) $ip = $_SERVER['REMOTE_ADDR'];

// initiate curl and set options
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://webservices.quova.com/ipinfo/' . $ip);
curl_setopt($ch, CURLOPT_USERPWD, $quovaUser . ':' . $quovaPass);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$data = curl_exec($ch);
$headers = curl_getinfo($ch);

// close curl
curl_close($ch);

// return XML data
if ($headers['http_code'] != '200') {
return false;
} else {
return($data);
}
}

// echo out XML response to test
echo quovaXML('4.2.2.2');

XML Response

Sample

The following is an example of the XML response from the HTTP request, assuming valid credentials. The XML response will be the same regardless of what language and platform were used to make the request.

<IpInfo xmlns="https://webservices.quova.com/ipinfo" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
    <IPAddress>4.2.2.2</IPAddress>
    <IPType>Mapped</IPType>
    <AnonymizerStatus/>    <Network>
        <Domain>
            <TopLevel>net</TopLevel>
            <SecondLevel>bbnplanet</SecondLevel>
        </Domain>
        <AOL>0</AOL>
        <Carrier>level 3 communications</Carrier>
        <ASN>3356</ASN>
        <Connection>tx</Connection>
        <LineSpeed>high</LineSpeed>
        <IPRoutingType>fixed</IPRoutingType>
    </Network>
    <Location>
        <Continent>
            <Name>north america</Name>
        </Continent>
        <Country>
            <Name>us</Name>
            <Confidence>99</Confidence>
        </Country>
        <Region>
            <Name>southwest</Name>
        </Region>
        <State>
            <Name>ca</Name>
            <Confidence>88</Confidence>
        </State>
        <DMA><Id>803</Id></DMA>
        <MSA><Id>31100</Id></MSA>
        <City>
            <Name>san juan capistrano</Name>
            <PostalCode>92675</PostalCode>
            <TimeZone>-8.0</TimeZone>
            <AreaCode>949</AreaCode>
            <Confidence>77</Confidence>
            <Coordinates>
                <Longitude>-117.662</Longitude>
                <Latitude>33.499</Latitude>
            </Coordinates>
        </City>
    </Location>
</IpInfo>

Reference

The following reference material describes the elements of the returned XML.

IpInfo

IpInfo is the top-level node that encapsulates the XML response.

Namespaces

xmlns - https://webservices.quova.com/ipinfo (default)
xmlns:i - http://www.w3.org/2001/XMLSchema-instance

Child nodes

Name	Type	Description	Remarks
AnonymizerStatus	AnonymizerType enumeration	Information about the Address Host data and its testing age within the Quova database.
IPAddress	String	The referenced IP address associated with the request.
IPType	String	Indicates if the IP address is publicly routable or reserved.	Possible values are `Mapped` or `Reserved`.
Location	Location	A Location node that provides information at the geographic level.
Network	Network	A Network node that provides information at the geographic level.

Location

The Location node represents the geo-location data for the referenced IP address.

Child nodes

Name	Type	Description
City	City	A City node that provides information at the city level.
Continent	Continent	A Continent node that provides information at the continent level.
Country	Country	A Country node that provides information at the country level.
DMA	DMA	A DMA node that provides information at the Designated Market Area level.
MSA	MSA	A MSA node that provides information at the Metropolitan or Micropolitan Statistical Area level.
Region	Region	A Region node that provides information at the region level.
State	State	A State node that provides information at the state level.

City

The City node represents the city data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
AreaCode	String	A phone number prefix assigned to the corresponding city.	Only one prefix is available per city. Prefixes are available in the U.S., Canada, and selectively in other countries. This field is still referred to as Area Code in some areas, although the field has been expanded outside the United States and Canada where the term is more commonly used. Note: The AreaCode does not include the telephone country code.
Confidence	Number	A measure of the confidence of precision, between 0 and 99, where a higher value indicates that the likelihood of a correct location assignment is higher.	This number is not a percentage, but a relative measure of confidence.
Country	Country	A Country node that provides information at the country level.
Coordinates	Coordinates	A Coordinates node that provides latitude and longitude geo-positional values.
Name	String	The name of the city.	Quova is able to geolocate users down to individual cities. These locations include, but are not limited to, major cities, known network hubs as well as cities that ensure proper coverage, especially in rural areas. There are over 95,000 distinct international locations that can be mapped by Quova. For a complete listing of cities, contact Quova support at support@quova.com.
PostalCode	String	A postal code assigned to the corresponding city.	Although many cities have more than one postal code, Quova derives only one per city. Available in the U.S., Canada, U.K., and selectively in other countries.
TimeZone	String	The time zone +/- offset from Greenwich Mean Time (GMT) represented as a floating point number.	Time zone is derived from city if assigned or country if city is unknown. If the city is unassigned and the country spans multiple time zones, a value of '999' is used in GeoPoint Data Files, while 'multizone' is returned by a GeoDirectory Server query.

Coordinates

The Coordinates node represents the geo-positional data for the referenced IP address.

Child nodes

Name	Type	Description
Latitude	Number	Latitude expressed as a floating point number with positive numbers representing North and negative numbers representing South.
Longitude	Number	Longitude expressed as a floating point number with positive numbers representing East and negative numbers representing West.

Continent

The Continent node represents the continental data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Name	String	The name of the continent.	Quova recognizes eight continents: Africa, Antarctica, Asia, Australia, Europe, North America, Oceania (Melanesia, Micronesia, Polynesia) and South America.

Country

The Country node represents the country data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Confidence	Number	A measure of the confidence of precision, between 0 and 99, where a higher value indicates that the likelihood of a correct location assignment is higher.	This number is not a percentage, but a relative measure of confidence.
Name	String	The full name of the country.	Quova provides coverage for every country that is covered by the ISO-3166-Alpha-2 code system.

DMA

The DMA node represents the designated market area data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Id	Number	The designated market area identifier.	Designated Market Areas (DMA) are assigned by Nielsen Media Research to identify TV stations that best reach an area and attract the most viewers. There are 210 total DMAs in the country. For example, San Francisco, San Jose, and Oakland all fall into the same DMA. For a complete listing, contact Quova support at support@quova.com.

MSA

The MSA node represents the metropolitan statistical area data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Id	Number	The metropolitan statistical area identifier.	Metropolitan or Micropolitan Statistical Area (MSA) is an attribute of U.S. and Puerto Rican cities defined by the U.S. Census Bureau. The current system identifies Core-Based Statistical Areas (CBSAs), with each CBSA consisting of a unique five-digit code, starting at 10000. CBSAs may be either Metropolitan or Micropolitan Statistical Areas. An area qualifies as a Metropolitan Statistical Area in one of two ways: 1) if it contains a city with a population of at least 50,000, or 2) if it contains an urbanized area of at least 50,000 and the total metro-area population is 100,000 or more. A Micropolitan Statistical Area must have at least one urban cluster of at least 10,000 but less than 50,000 population. For a complete listing, contact Quova support at support@quova.com. For more information on the differences between the statistical areas, visit the following website: http://www.census.gov/population/www/estimates/metroarea.html.

Network

The Network node represents the public network data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
AOL	String	Indicates that the user is or is not connecting through the AOL network.
ASN	String	A globally unique number assigned to a single network or a group of networks that is managed by a single administrative entity.
Carrier	String	The carrier organization, which is the entity corresponding to the Autonomous System Number (ASN).	Autonomous System Numbers are primarily used for the purpose of data routing via Border Gateway Protocol (BGP). There are over 27,000 active Autonomous System Numbers. A single organization can manage several ASNs, so in operation there are even fewer Autonomous Systems, or Carrier Organizations.
Connection	Connection enumeration	Indicates the data connection between a device and/or private LAN to the public Internet provider.
IPRoutingType	RoutingType enumeration	An attribute of the IP address that provides an assessment of the possible location of the user relative to the returned location of the IP address.
LineSpeed	Speed enumeration	The speed of the connection between the device or private LAN and the public Internet provider.

Region

The Region node represents the region data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Name	String	The name of the region.	For convenience, Quova has divided the U.S. into ten geographical regions: northeast, mid atlantic, south east, great lakes, midwest, south central, mountain, northwest, pacific, and south west. Regions are also available for the U.K., Brazil, Denmark and France. For a complete listing of regions, contact Quova support at support@quova.com.

State

The State node represents the state data for the referenced IP address.

Child nodes

Name	Type	Description	Remarks
Confidence	Number	A measure of the confidence of precision, between 0 and 99, where a higher value indicates that the likelihood of a correct location assignment is higher.	This number is not a percentage, but a relative measure of confidence.
Name	String	The name of the state.	Within the U.S., Quova provides coverage of all 50 states, as well as the District of Columbia. A complete region listing can be found under Reference Data, in the Downloads section of QuovaNet. Please refer to these text files for the latest information. Internationally, Quova provides the first-level administrative divisions within each country. If there are no such divisions within a given country, the term 'none' is reflected at the state level. A complete listing of International administrative divisions can be found under Reference Data, in the Downloads section of QuovaNet. Quova uses the anglicized and localized spelling for state values. For example, the state of Tuscany in Italy is denoted as "toscana" in Quova data.

Constants

AnonymizerType enumeration

These constants restrict the results for AnonymizerStatus in the IpInfo node.

Constant	Description	Remarks
PRIVATE	Indicates that the IP address allegedly contains anonymous proxies that are not publicly accessible. As such they cannot be routinely tested with automated tools.	These addresses typically belong to commercial ventures that sell anonymity services to the public. Addresses with this designation are derived from ownership information or obtained from trusted, high confidence sources.
ACTIVE	Indicates that the IP address tested positive within the last six months.
SUSPECT	Indicates that the IP address tested positive within the last two years, but not the last six months.
INACTIVE	Indicates that the IP address had no positive test results within the last two years.
UNKNOWN (or blank)	Indicates that no positive test results are currently available.	The initial anonymizer assignment is based upon other sources and has not yet been verified by Quova. If no positive test results are obtained, this address is removed from the list.

ConnectionType enumeration

These constants restrict the results for Connection in the Network node.

Constant	Description	Remarks
CABLE	Represents cable modem broadband circuits, offered by cable TV companies.	Speeds range from 128k to 100MB per second, and vary with the load placed on a given cable modem switch.
CACHE_PROXY	Indicates that the user is connecting via a proxy through either an Internet accelerator or content distribution service. It is possible the user is located in a different country from the IP.
CONSUMER_SATELLITE	Represents high-speed or broadband links between a consumer and a geosynchronous or low-earth orbiting satellite.	By default, IP addresses with a consumer satellite connection are assigned a satellite IP Routing Type as well.
DIALUP	Represents the consumer dial-up modem space	Dial-up operates at 56k per second. Providers include Earthlink, AOL and Netzero.
DSL	Represents Digital Subscriber Line broadband circuits, which include aDSL, iDSL, sDSL, etc.	In general DSL ranges in speed from 256k to 20MB per second.
FIXED_WIRELESS	Represents fixed wireless connections where the location of the receiver is fixed.	Includes WDSL providers such as Sprint Broadband Direct, as well as emerging WiMax providers.
FRAMERELAY	Represents frame relay circuits, which can range from low to high-speed and are used as a backup or alternative to T-1.	Most often these are high-speed links, so GeoPoint classifies them as such.
ISDN	Represents Integrated Services Digital Network high-speed copper-wire connectivity, supporting 128K per second speed, with modems and switches offering 1MB per second and greater speed.
MOBILE_WIRELESS	Represents cellular network providers.	Includes AT&T, Sprint and Verizon Wireless who employ CDMA, EDGE, EV-DO technologies. Speeds vary from 19.2k per second to 3MB per second.
OCX	Represents the optical connections, including OC-3, OC-48, OC-192, etc. which are used primarily by large backbone carriers.
TX	Represents T-3 circuits and T-1 circuits still used by many small and medium-sized companies.
UNKNOWN	Indicates that GeoPoint was unable to obtain any specific connection type or the connection type is not one listed above.
UNKNOWN_HIGH	Indicates that GeoPoint was unable to obtain any specific connection type or the connection type is not one listed above. However, it is estimated that the line speed is high.
UNKNOWN_LOW	Indicates that GeoPoint was unable to obtain any specific connection type or the connection type is not one listed above. However, it is estimated that the line speed is low.
UNKNOWN_MEDIUM	Indicates that GeoPoint was unable to obtain any specific connection type or the connection type is not one listed above. However, it is estimated that the line speed is medium.

RoutingType enumeration

These constants restrict the results for IPRoutingType in the Network node.

Constant	Description	Remarks
ANONYMIZER	Indicates that user's IP is located within a network block that has tested positive for anonymizer activity.	This means the user is potentially hiding their true location by using a service that deliberately proxies all user traffic. It is possible the user could be in any location. Further evidence for the specific IP can be provided by using the Anonymizer data available as part of the Gold Edition.
AOL	Indicates that the user is part of the AOL network.	Deprecated.
AOLDIALUP	Indicates that the user is part of the AOL network and is using a dial-up connection.	Quova can identify the user country in most cases. However, establishing the user location below country is not possible.
AOLPOP	Indicates that the user is part of the AOL network and is using a dial-up connection.	Quova can identify the user country in most cases. However, establishing the user location below country is not possible.
AOLPROXY	Indicates that the user is part of the AOL network using any kind of connection (broadband, dial-up, etc.).	Quova can identify the user country in most cases. However, establishing the user location below country is not possible.
CACHE_PROXY	Indicates that the user is connecting via a proxy through either an Internet accelerator or content distribution service.	It is possible the user is located in a different country from the IP.
FIXED	Indicates that the user location is likely to be at or near the IP location.
INTERNATIONAL_PROXY	Indicates that the user is connecting via a proxy (not anonymizer) that routes traffic from multiple countries.	It is possible the user is located in a different country from the IP. In many cases these are corporate networks that route traffic from international offices through a central point, often the corporate headquarters.
MOBILE_GATEWAY	Indicates that the user is using a gateway to connect mobile devices to the public Internet.	Many mobile operators, especially in Europe, service more than one country and backhaul traffic through centralized network hubs. For example, Research in Motion, provider of the Blackberry service, backhauls US and Canadian traffic through Canada. Therefore, it is possible the user is located in a different country from the IP.
NONE	Indicates that the routing type is not known or is not identifiable as one of the types listed above.	In applications where the cost of using location information incorrectly is low 'none' may be treated the same as 'fixed' connections.
POP	Indicates that the user is dialing into a regional ISP and is likely to be near the IP location.	However, the user could be dialing across geographical boundaries.
REGIONAL_PROXY	Indicates that the user is connecting via a proxy (not anonymizer) that routes traffic from multiple states within a single country.	It is possible the user is located in a different state from the IP. In many cases these are corporate networks that route traffic from regional offices through a central point, often the corporate headquarters.
SATELLITE	Indicates that the user is connecting to the Internet through a consumer satellite or a user connecting to the Internet with a backbone satellite provider where no information about the terrestrial connection is available.	In both cases, the user can be anywhere within the beam pattern of the satellite, which may span a continent or more. By definition, the satellite IP routing type does not by itself indicate that the end user is connected via satellite, rather that the user's traffic was routed through a satellite connection.
SUPERPOP	Indicates that the user is dialing into a multi-state or multi-national ISP and is not likely to be near the IP location.	Furthermore, the user could be dialing across geographical boundaries.

Speed enumeration

These constants restrict the results for LineSpeed in the Network node.

Constant	Description
HIGH	Indicates OCX, TX, and framerelay.
MEDIUM	Indicates consumer satellite, DSL, cable, fixed wireless, and ISDN.
LOW	Indicates dial-up and mobile wireless.
UNKNOWN	Indicates that GeoPoint was unable to obtain any line speed information.

Quova On Demand REST API

Table of Contents