Page tree
Skip to end of metadata
Go to start of metadata

Introduction

DOTS IP Address Validation (referred to as "IP Address Validation") is a publicly available XML web service that provides lookup information about an IP address. The service provides city, state, country, latitude and longitude coordinates, and proxy, ISP, and network information.

IP Address Validation can help provide instant location verification to websites or data enhancement to contact lists.

Integration

Integrating IP Address Validation into your application should be easy and straightforward. If you are using a common platform, Service Objects may already have sample code built that you can use: 
https://www.serviceobjects.com/developers/sample-code/ip-address-validation

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build you an example. Email support@serviceobjects.com for more details.

Web Service Structure

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic. Web services are too large of a topic to cover in this document, but Service Objects has developed its web services to be as easy to integrate and as accessible as possible.

IP Address Validation is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/gpp/

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
https://trial.serviceobjects.com/gpp/soap.svc?wsdl

Service XML Request Help Page

https://trial.serviceobjects.com/gpp/web.svc/xml/help

Service JSON Request Help Page

https://trial.serviceobjects.com/gpp/web.svc/json/help

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

This WSDL is the definition of the web service, defining its inputs, outputs, operations, etc. You will most likely have a tool read this WSDL and make the operations available to you in your application. Whenever your utilities or IDE asks for a WSDL path to IP Address Validation, you can provide the above path.

Every web service has operations that it offers to subscribers – methods that do different work and return different output. Examining the link above, you will notice several of these operations available, which are described in detail later on.

Code Snippets




IP Address Validation C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/gpp/soap.svc?wsdl
DOTSGeoPinPoint = new DOTSGeoPinPoint("DOTSGPP");
response = DOTSGeoPinPoint.GetLocationByIP_V2(IPAddress, licenseKey);
		
if (response.Error != null)
{
	//Process Error
}
else
{
	//Process Response		
}


IP Address Validation Java Code Snippet
IP result = null;
Error error = null;
// Create soap request
DOTSGeoPinPointLocator locator = new DOTSGeoPinPointLocator();
// use ssl
locator.setDOTSGeoPinPointSoapEndpointAddress("https://trial.serviceobjects.com/gpp/soap.svc?wsdl");
DOTSGeoPinPointSoap gpp = locator.getDOTSGeoPinPointSoap();
DOTSGeoPinPointStub soap = (DOTSGeoPinPointStub)gpp;
soap.setTimeout(5000);// set timeout
result = soap.getLocationByIP_V2(ip, key);
error = result.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
	throw new Exception();
}
 
//Process Results
if(error == null){
	//DOTS IP Address Validation Results	
}
//Process Errors
else{
	//DOTS IP Address Validation Error Results	
}


IP Address Validation PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/gpp/soap.svc?wsdl";

$params['IPAddress'] = $IPAddress;
$params['LicenseKey'] = $LicenseKey;

$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->GetLocationByIP_V2($params);
if (!isset($result->GetLocationByIP_V2Result->Error)) {
	foreach($result->GetLocationByIP_V2Result as $k=>$v) {
		echo $k . ", " . $v;
	}
} else {
	foreach($result->GetLocationByIP_V2Result->Error as $k=>$v) {
		echo $k . ", " . $v;
	}
}
?>


IP Address Validation RoR Code Snippets
		#Formats inputs into a hash to pass to Soap Client
		#Hash Keys must be named as they are shown here.
		message = 	{
					"IPAddress" => @request.ipaddress,
					"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@ipavresponse = :get_location_by_ip_v4_response
		@ipavresult = :get_location_by_ip_v4_result
		@ipaverror = :error

		#Set Primary and Backup URLs here as needed
		dotsIPAVPrimary = "https://trial.serviceobjects.com/gpp/soap.svc?wsdl"
		dotsIPAVBackup = "https://trial.serviceobjects.com/gpp/soap.svc?wsdl"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(wsdl: dotsIPAVPrimary)

			#Calls the operation with given inptus and converts response to a hash.
			response = client.call(:get_location_by_ip_v4, message: message).to_hash

			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(wsdl: dotsIPAVBackup)
			#Sets the response to the backclient call to the operation and converts response to a hash.
			response = backupclient.call(:get_location_by_ip_v4, message: message).to_hash
			processresults(response)

			#If backup url failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client	
			end
	end


IP Address Validation Python Code Snippets
		
    mIPAddress = IPAddress.get()
    if mIPAddress is None or  mIPAddress == "":
         mIPAddress = " "
    mLicenseKey = LicenseKey.get()
    if mLicenseKey is None or mLicenseKey == "":
        mLicenseKey = " "

    #Set the primary and backup URLs as needed
    primaryURL = 'https://trial.serviceobjects.com/gpp/soap.svc?wsdl'
    backupURL = 'https://trial.serviceobjects.com/gpp/soap.svc?wsdl'
    #This block of code calls the web service and prints the resulting values to the screen
    try:
        client = Client(primaryURL)
        result = client.service.GetLocationByIP_V4(IPAddress= mIPAddress, LicenseKey=mLicenseKey)
        #Handel response and check for errors
    #Tries the backup URL if the primary URL failed
    except:
        try:
            client = Client(backupURL)
            result = client.service.GetLocationByIP_V4(IPAddress= mIPAddress, LicenseKey=mLicenseKey)
            #Handel response and check for errors
        #If the backup call failed then this will display an error to the screen
        except:
            Label(swin.window, text='Error').pack()
            print (result)


IP Address Validation ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/gpp/soap.svc?wsdl");							  
				outputs = wsresponse.getLocationByIP_V4("#IPAddress#", "#LicenseKey#");
				writedump(outputs);
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/gpp/soap.svc?wsdl");							  
					outputs = wsresponse.getLocationByIP_V4("#IPAddress#", "#LicenseKey#");
				}
			}
			catch(any Exception)	{
		  		 writeoutput("An Error Has Occured. Please Reload and try again");		  		 
		 		}
	    }
</cfscript>


IP Address Validation VB Code Snippet
Try
    Dim ws As New IPAV.DOTSGeoPinPointSoapClient
    Dim response As IPAV.IP4
    response = ws.GetLocationByIP_V4(IPAddress.Text, LicenseKey.Text)
    If (response.Error Is Nothing) Then
        ProcessValidResponse(response)
    Else
        ProcessErrorResponse(response.Error)
    End If

Catch er As Exception
    Try
        ''Set Primary and Backup service references as necessary
        Dim wsbackup As New IPAV.DOTSGeoPinPointSoapClient
        Dim response As IPAV.IP4
        response = wsbackup.GetLocationByIP_V4(IPAddress.Text, LicenseKey.Text)
        If (response.Error Is Nothing) Then
            ProcessValidResponse(response)
        Else
            ProcessErrorResponse(response.Error)
        End If
    Catch ex As Exception
        resultsLabel.Visible = True
        resultsLabel.Text = ex.Message
    End Try
End Try


IP Address Validation Apex Code Snippet
wwwServiceobjectsCom.IP4 result;
try{
wwwServiceobjectsCom.DOTSGeoPinPointSoap client = new wwwServiceobjectsCom.DOTSGeoPinPointSoap();
result = client.GetLocationByIP_V4([IPAddress], [LicenseKey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSGeoPinPointSoap backupClient = new wwwServiceobjectsCom.DOTSGeoPinPointSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/GPP/api.svc/soap';
result = backupClient.GetLocationByIP_V4([IPAddress], [LicenseKey]);
}


IP Address Validation TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">'+
				   '<GetLocationByIP_V4 xmlns="http://www.serviceobjects.com/">'+
				   '<IPAddress>' + @ipaddress + '</IPAddress>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</GetLocationByIP_V4>'+
				   '</s:Body>'+
				   '</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/gpp/', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"https://www.serviceobjects.com/GetLocationByIP_V4"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://trial.serviceobjects.com/gpp/', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'trial.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"https://www.serviceobjects.com/GetLocationByIP_V4"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



IP Address Validation C# Rest Code Snippet
//encodes the URLs for the get Call. Set the primary and back urls as necessary
string primaryurl = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey);
string backupurl = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey);
IP4 wsresponse = httpGet(primaryurl);
//checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
if (wsresponse == null || (wsresponse.Error != null && wsresponse.Error.Number == "3"));
{
    wsresponse = httpGet(backupurl);
}
if (wsresponse.Error != null)
{
    ProcessErrorResponse(wsresponse.Error);
}
else
{
    ProcessSuccessfulResponse(wsresponse);
}


IP Address Validation Java Rest Code Snippet
JSONObject results = RestClient(mainURL);	
try {
	if (ErrorMessages != null || (results.getJSONObject("IP4").has("Error") && results.getJSONObject("IP4").getJSONObject("Error").get("Number") == "3")) {
		// BACKUP
		results = RestClient(backupURL);
	}
} catch (JSONException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}

return results;


IP Address Validation PHP Rest Code Snippet
$URL = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=".urlencode($IP)."&LicenseKey=".urlencode($LicenseKey);
//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=".urlencode($IP)."&LicenseKey=".urlencode($LicenseKey);
 
// Get cURL resource
$curl = curl_init();
curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'DOTS IP Address Validation'));
curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
// Send the request & save response to $resp
$resp = curl_exec($curl);
// Close request to clear up some resources
if($resp == false)
{
	echo "IN back up block";
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'DOTS IP Address Validation'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	if($resp == false)
	{
		echo "<b> Both rest calls failed </b>";
		curl_close($curl);
		return;
	}
}


IP Address Validation RoR Rest Code Snippets
#Set Primary and Backup URLs as needed. This method encodes and standardizes the URI to pass to the REST service.
primaryURL = URI.encode("https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=" + ipaddress + "&LicenseKey=" + licensekey)
backupURL = URI.encode("https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=" + ipaddress + "&LicenseKey=" + licensekey)
#These are set to access the hash that is returned
@ipavresult ="IP4"
@ipaverror = "Error"
#Begins the call the RESTful web service
begin
response = HTTParty.get(primaryURL, timeout: default_timeout)
#processes the response to display to the screen
#Passes the response returned from HTTParty and processes them depending on the results
processresults(response)

rescue StandardError => e
		begin
		#uses the backupURl in the event that the service encountered an error
		response = HTTParty.get(backupURL, timeout: default_timeout)
  
  #processes the response returned from using the backupURL
		processresults(response)
  #If the backup url railed this will raise an error and display the 
  #error message returned from the HTTParty gem.
		rescue StandardError => error
			@status = error.message
			@displaydata = {"Error" => "A Big Error Occured"}
		end
end


IP Address Validation Python Rest Code Snippets
primaryURL = 'https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?'
backupURL = 'https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?'
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
inputs = {'IPAddress': mIPAddress, 'LicenseKey': mLicenseKey}
try:
    result = requests.get(primaryURL, params=inputs)
    #Parses the XML response from the service into a python dictionary type
    outputs = xmltodict.parse(result.content)
    #checks the output for Errors and displays the info accordingly
    if 'Error' in outputs['IP4']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['IP4']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        #This code removes extra entries that were parsed in from the xml response
        outputs['IP4'].pop("@xmlns:xsi", None)
        outputs['IP4'].pop("@xmlns:xsd", None)
        outputs['IP4'].pop("@xmlns", None)
        for key, value in outputs['IP4'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
except:
    try:
        result = requests.get(backupURL, params=inputs)
        #Parses the XML response from the service into a python dictionary type
        outputs = xmltodict.parse(result.content)
        #checks the output for Errors and displays the info accordingly
        if 'Error' in outputs['IP4']:
            #loops through the response from the service and prints the values to the screen.
            for key, value in outputs['IP4']['Error'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()
        else:
            #This code removes extra entries that were parsed in from the xml response
            outputs['IP4'].pop("@xmlns:xsi", None)
            outputs['IP4'].pop("@xmlns:xsd", None)
            outputs['IP4'].pop("@xmlns", None)
            for key, value in outputs['IP4'].iteritems():
                Label(swin.window, text=str(key) + " : " + str(value)).pack()


IP Address Validation ColdFusion Rest Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?IPAddress=#IPAddress#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
	<cfcatch >
		<cftry>
			<cfset backupURL = "https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?IPAddress=#IPAddress#&LicenseKey=#LicenseKey#">
			<cfhttp url="#backupURL#" method="get" result="response">
			<cfset outputs = XmlParse(response.FileContent)>				
			<cfcatch >
				<cfoutput >
					The Following Error Occured: #response.StatusCode#
				</cfoutput>
			</cfcatch>
		</cftry>
	</cfcatch>
	</cftry>
</cfif>


IP Address Validation VB Rest Code Snippet
Try
    'encodes the URLs for the get Call. Set the primary and back urls as necessary
    Dim primaryurl As String = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey)
    Dim backupurl As String = "https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4=" + WebUtility.UrlEncode(ipaddress) + "&LicenseKey=" + WebUtility.UrlEncode(licensekey)
    Dim wsresponse As IPResponse.IP4 = httpGet(primaryurl)
    'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
    If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].Number = "3") Then

    End If
    If True Then
        wsresponse = httpGet(backupurl)
    End If
    If wsresponse.[Error] IsNot Nothing Then
        ProcessErrorResponse(wsresponse.[Error])
    Else
        ProcessSuccessfulResponse(wsresponse)

    End If
Catch ex As Exception
    'Displays the relevant error mesasge if both backup and primary urls failed.
    StatusLabel.Text = ex.Message
    StatusLabel.Visible = True
End Try


IP Address Validation TSQL Rest Code Snippet
BEGIN
	SET @sUrl = 'https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?IPAddress=' + @ipaddress + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?IPAddress=' + @ipaddress + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace IPAddressValidation
{
    public partial class _Default : System.Web.UI.Page
    {
        private com.serviceobjects.trial.DOTSGeoPinPoint GeoPinPoint;
        private com.serviceobjects.trial.IP IPResult;
    
        protected void Page_Load(object sender, EventArgs e)
        {
            // Create proxy to DOTS IP Address Validation service for convenient calls to methods
            GeoPinPoint = new com.serviceobjects.trial.DOTSGeoPinPoint();
            IPResult = null;
            ResultLabel.Visible = false;
        }
        protected void btn_GO_Click(object sender, EventArgs e)
        {
            try
            {   
                // Call DOTS IPAddress Validaiton using GetLocationByIP_V2 and store result in IPResult Object
                IPResult = GeoPinPoint.GetLocationByIP_V2(inputIPAddress.Text, inputLicenseKey.Text);

                DataTable dtContact = new DataTable();
                DataTable dtError = new DataTable();
                /*declaring a table to hold the contact information*/
                dtContact.Columns.Add(new DataColumn("Output", typeof(string)));
                dtContact.Columns.Add(new DataColumn("Values", typeof(string)));
                if (IPResult.Error != null)
                {   
                    // If DOTS IP Address Validation returns any errors capture them and output here
                    dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                    dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                    dtError.Rows.Add("Error", IPResult.Error.Desc);
                    dataGrid1.Visible = false;
                    dataGrid2.DataSource = new DataView(dtError);
                    dataGrid2.DataBind();
                }
                else
                {   // No errors found. Create rows for GeoPinPoint output and add values
                    dtContact.Rows.Add("City", IPResult.City);
                    dtContact.Rows.Add("Region", IPResult.Region);
                    dtContact.Rows.Add("Country", IPResult.Country);
                    dtContact.Rows.Add("CountryISO3", IPResult.CountryISO3);
                    dtContact.Rows.Add("CountryISO2", IPResult.CountryISO2);
                    dtContact.Rows.Add("Longitude", IPResult.Longitude);
                    dtContact.Rows.Add("Latitude", IPResult.Latitude);
                    dtContact.Rows.Add("Certainty", IPResult.Certainty);
                    dtContact.Rows.Add("IsProxy", IPResult.IsProxy);
                    dtContact.Rows.Add("ProxyType", IPResult.ProxyType);
                    dtContact.Rows.Add("ISP", IPResult.ISP);
                    dtContact.Rows.Add("NetBlockOwner", IPResult.NetblockOwner);
                    // Add data rows to result datagrid
                    dataGrid1.Visible = true;
                    dataGrid2.Visible = false;
                    dataGrid1.DataSource = new DataView(dtContact);
                    dataGrid1.DataBind();

                }//end if IPResult.Error != null
            }
            catch (Exception ex)
            {   // Catch any errors while callling DOTS Services and output them to ResultLabel
                ResultLabel.Text = ex.Message;
                ResultLabel.Visible = true;
            }
        }
    }
}


GetCountryByIP Example Request and Response

XML Request: 
https://trial.serviceobjects.com/gpp/GeoPinPoint.asmx/GetCountryByIP?IPAddress=209.85.173.104&LicenseKey=licenseKey


XML Response
<CountryByIPResponse xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<CountryIPLocationInfo>
<Country>United States</Country>
<Cntry>USA</Cntry>
<Ctry>US</Ctry>
<Latitude>37.419201</Latitude>
<Longitude>-122.057404</Longitude>
<IsPublicProxy>Unknown</IsPublicProxy>
</CountryIPLocationInfo>
</CountryByIPResponse>

GetLocationByIP_V2 Example Request and Response

XML Request: 
https://trial.serviceobjects.com/gpp/GeoPinPoint.asmx/GetLocationByIP_V2?IPAddress=209.85.173.104&LicenseKey=licenseKey


XML Response
<LocationByIP_V2Response xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<IPLocationInfo>
<City>Mountain View</City>
<Region>CA</Region>
<Country>United States</Country>
<CountryISO3>USA</CountryISO3>
<CountryISO2>US</CountryISO2>
<Longitude>-122.057404</Longitude>
<Latitude>37.419201</Latitude>
<Certainty>95</Certainty>
<IsProxy>FALSE</IsProxy>
<ProxyType>NONE</ProxyType>
<ISP>Google</ISP>
<NetblockOwner>Google</NetblockOwner>
<Debug/>
</IPLocationInfo>
</LocationByIP_V2Response

GetLocationByIP_V3 Example Request and Response

URL Request: 
https://trial.serviceobjects.com/gpp/GeoPinPoint.asmx/GetLocationByIP_V3?IPAddress=209.85.173.104&LicenseKey=licenseKey


XML Response
<LocationByIP_V3Response xmlns="http://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<IPLocationInfo>
<Certainty>95</Certainty>
<City>Mountain View</City>
<Region>CA</Region>
<Country>United States</Country>
<CountryISO3>USA</CountryISO3>
<CountryISO2>US</CountryISO2>
<PostalCode>94043</PostalCode>
<MetroCode>807</MetroCode>
<DMA>San Francisco - Oakland - San Jose</DMA>
<StateFIPS>06</StateFIPS>
<CountyFIPS>085</CountyFIPS>
<Latitude>37.419201</Latitude>
<Longitude>-122.057404</Longitude>
<IsProxy>FALSE</IsProxy>
<ProxyType>NONE</ProxyType>
<PossibleMobileDevice>FALSE</PossibleMobileDevice>
<ISP>Google</ISP>
<NetblockOwner>Google</NetblockOwner>
<Debug/>
</IPLocationInfo>
</LocationByIP_V3Response>

GetLocationByIP_V4 Example Request and Response

XML URL Request: 
https://trial.serviceobjects.com/GPP/web.svc/xml/GetLocationByIP_V4?IPAddress=8.8.8.8&LicenseKey=licenseKey


XML Response
<IP4 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.serviceobjects.com/">
<Certainty>95</Certainty>
<City>New York</City>
<Region>NY</Region>
<Country>United States</Country>
<CountryISO3>USA</CountryISO3>
<CountryISO2>US</CountryISO2>
<PostalCode/>
<MetroCode/>
<DMA>New York</DMA>
<StateFIPS>36</StateFIPS>
<CountyFIPS>061</CountyFIPS>
<Latitude>40.7488</Latitude>
<Longitude>-73.9846</Longitude>
<IsProxy>FALSE</IsProxy>
<ProxyType>NONE</ProxyType>
<PossibleMobileDevice>FALSE</PossibleMobileDevice>
<ISP>Google</ISP>
<NetblockOwner>Google</NetblockOwner>
<HostNames>google-public-dns-a.google.com</HostNames>
<IPNoteCodes/>
<IPNotes/>
</IP4>


JSON URL Request: 
https://trial.serviceobjects.com/GPP/web.svc/json/GetLocationByIP_V4?IPAddress=8.8.8.8&LicenseKey=licenseKey


XML Response
{"Certainty":95,"City":"New York","Region":"NY","Country":"United States","CountryISO3":"USA","CountryISO2":"US","PostalCode":"","MetroCode":"","DMA":"New York","StateFIPS":"36","CountyFIPS":"061","Latitude":40.7488,"Longitude":-73.9846,"IsProxy":"TRUE","ProxyType":"PUBLIC","PossibleMobileDevice":"FALSE","ISP":"Google","NetblockOwner":"Google","HostNames":"google-public-dns-a.google.com","IPNoteCodes":"1","IPNotes":"PotentiallyMaliciousIP","Debug":""}

List of Operations

This document defines the input, output and behavior of the web service operations in IP Address Validation.

GetGeoLocationByIP_V4 (Recommended Operation) – Returns geographic location, proxy, hostname and US region information for a given IP address.
GetCountryByIP – Like GetLocationByIP, but only returns the country name and abbreviations, and the latitude longitude of the country centroid.
GetLocationByIP_V2 – A version of GetLocationByIP that adds several new elements including proxy information, ISP, and the netblock owner. (Deprecated: Use GetLocationByIP_V4) 
GetGeoLocationByIP_V3 – Returns geographic location, proxy and US region information for a given IP address. (Deprecated: Use GetLocationByIP_V4) 
GetLocationByIP – Returns geographic location information for a given IP address. (Deprecated: Use GetLocationByIP_V4)  


GetLocationByIP_V4 (Recommended Operation)

Returns geographic location, proxy, host name and US region information for a given IP address. 

GetLocationByIP_V4 Inputs

Name

Type

Description

IPAddress

String

IP address to look up, for example, "209.85.173.104"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/demographics-more/ip-address-validation

GetLocationByIP_V4 Outputs

Name

Type

Values

Description

Certainty

Int

0 to 100

Rating of how accurate the outputs are likely to be.

City

String

Varies

The city location of the IP address.

Region

String

Varies

The state location of the IP address.

Country

String

Varies

The country location of the IP address.

CountryISO3

String

Varies

The 3-letter country abbreviation.

CountryISO2

String

Varies

The 2-letter country abbreviation.

PostalCode*StringVariesThe US postal code of the IP address.
MetroCode*StringVariesThe numerical metropolitan code for the DMA of the IP address' location.
DMA*StringVariesThe Designated Market Area for the location of the IP address.
StateFIPS*StringVariesThe state Federal Information Processing Standards code for the IP address. This code is used to uniquely identify states.
CountyFIPS*StringVariesThe County Federal Information Processing Standards code for the location of the IP address. This code is used to uniquely identify counties throughout the US.

Latitude

Double

Varies

The latitude coordinate for the IP address.

Longitude

Double

Varies

The longitude coordinate for the IP address.

IsProxy

String

"TRUE" or "FALSE"

Indicates whether the IP address is a known proxy.

ProxyType

String

"NONE", "PRIVATE", "PUBLIC", "ANONYMOUS", "SATELLITE"

Indicates the type of proxy. Further description of proxy type can be found in the table below

PossibleMobileDeviceString"TRUE" or "FALSE"Indicates if the IP address is believed to be used by mobile devices.

ISP

String

Varies

The ISP which assigns the IP address.

NetblockOwner

String

Varies

The network owner to which the IP address is allocated.

HostNamesStringVariesThe host name associated with the IP address. If more than one host name is found then the names will be returned a comma delimited list. Will return if no host names are found.
IPNoteCodesStringVariesDisplays additional notes about the IP that were found during the validation process. Returns zero or more numerical note codes in a comma-separated list.**
IPNotesStringVariesContains the note flag(s) that corresponds to the Notes Codes. Returns zero or more notes flags in a comma-separated list.**

Debug

String

Varies


Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

*Applies only to IP addresses located within the United States
**New codes and descriptions will be added as new features become available and the number of codes will increase in time.


Proxy TypeDefinition
NONE No proxy was found at the given IP address.
PRIVATEA dedicated server that is used exclusively by one client at a time.
PUBLIC

A proxy server that is openly available and accessible by any internet user.

ANONYMOUSA proxy server that does not reveal the users real IP address. 
SATELLITEProxy is provided by a satellite connection. Typically used to provide internet connection to rural areas.


NoteCodeDescription

PotentiallyMaliciousIP,

1

Indicates that the IP address has a high probability of being bad/malicious.

MaliciousIP2Indicates that the IP address is almost certainly bad/malicious.

NOTE: Due to the nature of IP addresses and how frequently they can be reassigned, an IP address may be considered malicious when the real-time check was performed but may stop being so afterward. Therefore it is important not to permanently reject or ban a malicious IP address.


 

GetCountryByIP

Returns the country that the IP address is located in.

GetCountryByIP Inputs

Name

Type

Description

IPAddress

String

IP address to look up, for example, "209.85.173.104"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/demographics-more/ip-address-validation

GetCountryByIP Outputs

Name

Type

Values

Description

Country

String

Varies

The country location of the IP address.

Cntry

String

Varies

The 3-letter country abbreviation.

Ctry

String

Varies

The 2-letter country abbreviation.

Longitude

Double

Varies

The longitude coordinate for the IP address.

Latitude

Double

Varies

The latitude coordinate for the IP address.

IsPublicProxy

String

Varies

Indicates whether the IP address is a known public proxy.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

GetLocationByIP 

Returns geographic location information for a given IP address.

GetLocationByIP Inputs

Name

Type

Description

IPAddress

String

IP address to look up, for example, "209.85.173.104"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/demographics-more/ip-address-validation

GetLocationByIP Outputs

Name

Type

Values

Description

City

String

Varies

The city location of the IP address.

Region

String

Varies

The state location of the IP address.

Country

String

Varies

The country location of the IP address.

Longitude

Double

Varies

The latitude coordinate for the IP address.

Latitude

Double

Varies

The longitude coordinate for the IP address.

Certainty

Int

0 to 100

Rating of how accurate the outputs are likely to be.

IsProxy

String

"TRUE" or "FALSE"

Indicates whether the IP address is a known proxy.

IsPublicProxy

String

Varies

Indicates whether the IP address is a known public proxy.

Network

String

Varies

The network to which the IP address is registered.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

GetLocationByIP_V2 

Returns geographic location and proxy information for a given IP address.

GetLocationByIP_V2 Inputs

Name

Type

Description

IPAddress

String

IP address to look up, for example, "209.85.173.104"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/demographics-more/ip-address-validation

GetLocationByIP_V2 Outputs

Name

Type

Values

Description

City

String

Varies

The city location of the IP address.

Region

String

Varies

The state location of the IP address.

Country

String

Varies

The country location of the IP address.

CountryISO3

String

Varies

The 3-letter country abbreviation.

CountryISO2

String

Varies

The 2-letter country abbreviation.

Longitude

Double

Varies

The latitude coordinate for the IP address.

Latitude

Double

Varies

The longitude coordinate for the IP address.

Certainty

Int

0 to 100

Rating of how accurate the outputs are likely to be.

IsProxy

String

"TRUE" or "FALSE"

Indicates whether the IP address is a known proxy.

ProxyType

String

"NONE", "PRIVATE", "PUBLIC", "ANONYMOUS", "SATELLITE"

Indicates the type of proxy.

ISP

String

Varies

The ISP which assigns the IP address.

NetblockOwner

String

Varies

The network owner to which the IP address is allocated.

Debug

String

Varies


Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

GetLocationByIP_V3

Returns geographic location, proxy and US region information for a given IP address. 

GetLocationByIP_V3 Inputs

Name

Type

Description

IPAddress

String

IP address to look up, for example, "209.85.173.104"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/demographics-more/ip-address-validation

GetLocationByIP_V3 Outputs

Name

Type

Values

Description

City

String

Varies

The city location of the IP address.

Region

String

Varies

The state location of the IP address.

Country

String

Varies

The country location of the IP address.

CountryISO3

String

Varies

The 3-letter country abbreviation.

CountryISO2

String

Varies

The 2-letter country abbreviation.

PostalCode*StringVariesThe US postal code of the IP address.
MetroCode*StringVariesThe numerical metropolitan code for the DMA of the IP address' location.
DMA*StringVariesThe Designated Market Area for the location of the IP address.
StateFIPS*StringVariesThe state Federal Information Processing Standards code for the IP address. This code is used
to uniquely identify states. 
CountyFIPS*StringVariesThe County Federal Information Processing Standards code for the location of the IP address.
This code is used to uniquely identify counties.  

Longitude

Double

Varies

The latitude coordinate for the IP address.

Latitude

Double

Varies

The longitude coordinate for the IP address.

Certainty

Int

0 to 100

Rating of how accurate the outputs are likely to be.

IsProxy

String

"TRUE" or "FALSE"

Indicates whether the IP address is a known proxy.

ProxyType

String

"NONE", "PRIVATE", "PUBLIC", "ANONYMOUS", "SATELLITE"

Indicates the type of proxy.

PossibleMobileDeviceString"TRUE" or "FALSE"Indicates if the IP address is believed to be used by mobile devices.

ISP

String

Varies

The ISP which assigns the IP address.

NetblockOwner

String

Varies

The network owner to which the IP address is allocated.

Debug

String

Varies


Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

*Applies only to IP addresses located within the United States

Error Codes

Error codes in IP Address Validation are the same for all operations. They are as follows:

Error Code 1 – "Input cannot be less than zero length"

This error means the web service did not get any input. The connection to the service was made, and data was transferred, but no parameters were passed that the service could understand. 
This error often happens when input is passed to the service with namespaces that the service does not understand. Applying a namespace to any of the parameters (Email or LicenseKey, in this service) will cause this error. Additionally, requests made in the "rpc/encoded" format will cause this error. The only namespace that should appear in any element is the "http://www.serviceobjects.com" namespace on the root GetLocationByIP_V2 element as so:

<GetLocationByIP_V2 xmlns="http://www.serviceobjects.com/">


Note, however, that the namespace is not applied to the GetLocationByIP_V2 element, it is only present.

Error Code 2 – Various descriptions

This error code appears when various errors occur, but are of the expected nature. Oftentimes, maligned or incomplete input will cause an error 2.

Error Code 4 – Various descriptions

An error code 4 is a fatal error and it means something has seriously gone wrong. You should never see an error code 4 in a live production environment.

Frequently Asked Questions

Which Operation Should You Use? GetLocationByIP, GetCountryByIP, or GetLocationByIP_V4?

Picking which operation you want to use is simple. If you only need to know which country an IP address belongs to, GetCountryByIP is the best operation. If you can use more specific data, such as the region or city, then GetLocationByIP_V4 is the best operation. Use of GetLocationByIP (or the V2 or V3 operation) is not recommended, as it is deprecated and replaced by GetLocationByIP_V4. The best suggestion is to try out each operation to find the data you need.

Why is there an operation that ends with a V4?

When we need to enhance our service in a way that changes input or output interfaces, it's best to create a new operation. If we change the interface of an existing operation, we could potentially adversely affect many existing customers. 
If you are a new client or in a position to make a change, it's usually best to switch to the new operation as it likely has important new enhancements.

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses. 
The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to:
https://trial.serviceobjects.com/gpp/

Next, try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code won't be able to connect either. Contact your systems or network administrator to resolve why you are not able to connect to Service Objects.

I'm Not a Programmer. How Do I Use DOTS IP Address Validation?

Service Objects runs batches for you! A free batch trial is available at https://www.serviceobjects.com/batch/upload.

Conclusion

Service Objects is proud to offer you a free trial of DOTS IP Address Validation US.

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS IP Address Validation, please contact sales@serviceobjects.com.


  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels