Introduction
Integration
https://www.serviceobjects.com/sample-code/?service=34
DOTS Address Geocode – US is a public XML web service that supports SOAP, POST and GET operations.
SOAP is done via POST, only with special XML markup in the post-body.
Code Snippets
- Code Snippets
- Full Sample Code Demonstrating Failover
- URL Formats/Request and Response
- SOAP
- Rest
- C#
- Java
- PHP
- ROR
- Python
- ColdFusion
- VB
- Apex
- TSQL
GeoCoder C# Code Snippet
//Add a service to your application https://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL
GCRClient_Primary = new GCRLibraryClient("DOTSGCR");
response = GCRClient_Primary.GetBestMatch_V3(Address, City, State, PostalCode, licenseKey);
if (response.Error != null)
{
//Process Error
}
else
{
//Process Response
}
GeoCoder Java Code Snippet
BestMatch_V3Response resp = null;
BestMatchInfo result = null;
Error error = null;
// Create soap request
GCRLibraryLocator locator = new GCRLibraryLocator();
// use ssl
locator.setDOTSGeoCoderEndpointAddress("https://trial.serviceobjects.com/gcr/GeoCoder.asmx");
IGCRLibrary gcr = locator.getDOTSGeoCoder();
DOTSGeoCoderStub soap = (DOTSGeoCoderStub)gcr;
soap.setTimeout(5000);// set timeout
resp = soap.getBestMatch_V3(address, city, state, postalcode, key);
result = resp.getGetBestMatch_V3Result();
error = resp.getError();
if(resp == null || (error != null && error.getTypeCode() == "3"))
{
throw new Exception();
}
//Process Results
if(error == null){
//DOTS GeoCode Results
}
//Process Errors
else{
//DOTS GeoCode Error Results
}
GeoCoder PHP Code Snippets
<?php
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL";
$params['Address'] = $address;
$params['City'] = $city;
$params['State'] = $state;
$params['PostalCode'] = $postalCode;
$params['LicenseKey'] = $LicenseKey;
$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->GetBestMatch_V3($params);
if (!isset($result->GetBestMatch_V3Result ->Error)) {
foreach($result->GetBestMatch_V3Result ->BestMatchInfo as $k=>$v) {
echo $k . ", " . $v;
}
} else {
foreach($result->GetBestMatch_V3Result ->Error as $k=>$v) {
echo $k . ", " . $v;
}
}
?>
GeoCoder RoR Code Snippets
class RequestsController < ApplicationController
def show
@request = Request.find(params[:id])
#Formats inputs into a hash to pass to Soap Client
#Hash Keys must be named as they are shown here.
message = {
"Address" => @request.address,
"City" => @request.city,
"State" => @request.state,
"PostalCode" => @request.postalcode,
"LicenseKey" => @request.licensekey,
}
#Implemented to make the code more readable when accessing the hash
@agusresponse = :get_best_match_v3_response
@agusresult = :get_best_match_v3_result
@aguserror = :error
#Set Primary and Backup URLs here as needed
dotsAGUSPrimary = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL"
dotsAGUSBackup = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx?WSDL"
begin
#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
client = Savon.client( wsdl: dotsAGUSPrimary,
element_form_default: :qualified,
convert_request_keys_to: :camelcase
)
#Calls the with given inptus and converts response to a hash.
response = client.call(:get_best_match_v3, 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 the Backup url and attempt to retrieve data.
rescue Savon::Error => e
begin
backupclient = Savon.client( wsdl: dotsAGUSBackup,
element_form_default: :qualified,
convert_request_keys_to: :camelcase
)
#Sets the response to the backclient call to the operation and converts response to a hash.
response = backupclient.call(:get_best_match_v3, message: message).to_hash
processresults(response)
#If the backup url failed, this will display the error received from the server
rescue Savon::Error =>error
@status = error
@displaydata = {"error" => "A Big Error Occured"}
end
end
end
private
def processresults(response)
#Processes Error Response from soap Client
#Processes Valid response from soap client
end
end
Address Geocode US Python Code Snippet
mAddress = Address.get()
if mAddress is None or mAddress == "":
mAddress = " "
mCity = City.get()
if mCity is None or mCity == "":
mCity = " "
mState = State.get()
if mState is None or mState == "":
mState = " "
mPostalCode = PostalCode.get()
if mPostalCode is None or mPostalCode == "":
mPostalCode = " "
mLicenseKey = LicenseKey.get()
if mLicenseKey is None or mLicenseKey == "":
mLicenseKey = " "
#Set the primary and backup URLs as needed
primaryURL = 'https://sws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL'
backupURL = 'https://sws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL'
#This block of code calls the web service and prints the resulting values to the screen
try:
client = Client(primaryURL)
result = client.service.GetBestMatch_V3(Address=mAddress, City=mCity, State=mState, PostalCode=mPostalCode, LicenseKey=mLicenseKey)
#Loops through either the error result or proper result and displays values to the screen.
#Handel response and check for errors
#Tries the backup URL if the primary URL failed
except:
try:
client = Client(backupURL)
result = client.service.GetBestMatch_V3(Address=mAddress, City=mCity, State=mState, PostalCode=mPostalCode, 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)
Address GeoCoder ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfscript>
try
{
if (isDefined("form.Action") AND Action neq "")
{
wsresponse = CreateObject("webservice", "https://sws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL");
outputs = wsresponse.getBestMatch_V3("#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
}
}
catch(any Exception){
try
{
if (isDefined("form.Action") AND Action neq "")
{
wsresponse = CreateObject("webservice", "https://sws.serviceobjects.com/gcr/GeoCoder.asmx?WSDL");
outputs = wsresponse.getBestMatch_V3("#Address#", "#City#", "#State#", "#PostalCode#" ,"#LicenseKey#");
}
}
catch(any Exception)
{
writeoutput("An Error Has Occured. Please Reload and try again #Exception.message#");
}
}
</cfscript>
Address GeoCoder VB Code Snippet
Try
Dim ws As New AGUS.DOTSGeoCoderSoapClient
Dim response As AGUS.Location_V3
response = ws.GetBestMatch_V3(Address.Text, City.Text, State.Text, PostalCode.Text, LicenseKey.Text)
If (response.Error Is Nothing) Then
ProcessValidResponse(response)
Else
ProcessErrorResponse(response.Error)
End If
Catch
''Set the Primary and Backup Service References as necessary
Try
Dim wsbackup As New AGUS.DOTSGeoCoderSoapClient
Dim response As AGUS.Location_V3
response = wsbackup.GetBestMatch_V3(Address.Text, City.Text, State.Text, PostalCode.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
Address GeoCoder Apex Code Snippet
wwwServiceobjectsCom.Location_V3 result;
try{
wwwServiceobjectsCom.DOTSGeoCoderSoap client = new wwwServiceobjectsCom.DOTSGeoCoderSoap();
result = client.GetBestMatch_V3([Address], [City], [State], [PostalCode], [LicenseKey]);
}
catch(Exception ex){
//If the first request failed try the failover endpoint
wwwServiceobjectsCom.DOTSGeoCoderSoap backupClient = new wwwServiceobjectsCom.DOTSGeoCoderSoap();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/AGUS/api.svc/soap';
result = backupClient.GetBestMatch_V3([Address], [City], [State], [PostalCode], [LicenseKey]);
}
Address GeoCoder 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">'+
'<GetBestMatch_V3 xmlns="https://www.serviceobjects.com/">'+
'<Address>' + @address + '</Address>'+
'<City>' + @City + '</City>'+
'<State>' + @State + '</State>'+
'<PostalCode>' + @postalcode + '</PostalCode>'+
'<LicenseKey>' + @key + '</LicenseKey>'+
'</GetBestMatch_V3>'+
'</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://sws.serviceobjects.com/gcr/GeoCoder.asmx', false
EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'sws.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/GetBestMatch_V3"'
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://swsbackup.serviceobjects.com/gcr/GeoCoder.asmx', false
EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'swsbackup.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/GetBestMatch_V3"'
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
- C# Rest
- Java Rest
- PHP Rest
- RoR Rest
- Python Rest
- ColdFusion Rest
- VB Rest
- TSQL Rest
GeoCoder C# Rest Code Snippet
string mainURL = WEB_SERVICE_PRIMARY_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
string backupURL = WEB_SERVICE_BACKUP_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
try
{
result = HttpGet(mainURL);
//NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP
if (result == null || (result.Error != null && result.Error.Number == "3"))
{
return HttpGet(backupURL);
}
else
{
return result;
}
}
catch (Exception e)
{ //ERROR IN MAIN URL - USING BACKUP
return HttpGet(backupURL);
}
GeoCoder Java Rest Code Snippet
JSONObject results = RestClient(mainURL);
try {
if (ErrorMessages != null || (results.getJSONObject("Location_V3").has("Error") && results.getJSONObject("Location_V3").getJSONObject("Error").get("Number") == "3")) {
// BACKUP
results = RestClient(backupURL);
}
} catch (JSONException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
return results;
GeoCoder PHP Rest Code Snippets
$URL = "https://trial.serviceobjects.com/GCR/api.svc/GetBestMatch_V3?".rawurlencode($Address)."/".rawurlencode($City)."/".rawurlencode($State)."/".rawurlencode($PostalCode)."/".rawurlencode($LicenseKey)."?format=json";
// The actual backup url will be provided to you once you purchase a license key
$backupURL = "https://trial.serviceobjects.com/rest/GCR/api.svc/BestMatchInfo/V3/".rawurlencode($Address)."/".rawurlencode($City)."/".rawurlencode($State)."/".rawurlencode($PostalCode)."/".rawurlencode($LicenseKey)."?format=json";
// Get cURL resource
$curl = curl_init();
curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Address Validation 3'));
//Https peer certification validation turned off
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT_MS, $TIMEOUT); //timeout in milliseconds
// Send the request & save response to $resp
$resp = curl_exec($curl);
$status = curl_getinfo($curl);
$decoded = json_decode($resp, TRUE);
if($resp == FALSE ||
(isset ($decoded['Error']) != NULL &&
$decoded['Error']['Number'] == 3) ||
(isset($status) && $status['http_code'] != 200))
{
// the first service has failed over
// create a new request to the backURL
$curl2 = curl_init();
curl_setopt_array($curl2, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Email Validation 3'));
//Https peer certification validation turned off
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl2, CURLOPT_CONNECTTIMEOUT_MS, $TIMEOUT); //timeout in milliseconds
// Send the request & save response to $resp
$resp = curl_exec($curl2);
$decoded = json_decode($resp, TRUE);
if($resp == false)
{
echo "<b> Both rest calls failed </b>";
curl_close($curl2);
return;
}
}
GeoCoder RoR Rest Code Snippets
@request = Request.find(params[:id])
#This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
default_timeout = 10
address = @request.address
city = @request.city
state = @request.state
postalcode = @request.postalcode
licensekey = @request.licensekey
#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/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
backupURL = URI.encode("https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey)
#These are set to access the hash that is returned
@agresult ="Location_V3"
@agerror = "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
Address Geocode US Python Code Snippet
primaryURL = 'https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?'
backupURL = 'https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?'
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
inputs = {'Address': mAddress, 'City': mCity, 'State': mState, 'PostalCode': mPostalCode, '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['Location_V3']:
#loops through the response from the service and prints the values to the screen.
for key, value in outputs['Location_V3']['Error'].iteritems():
Label(swin.window, text=str(key) + " : " + str(value)).pack()
else:
#Removes unnecessary entries that were parsed into the python dictionary from XML response of service
outputs['Location_V3'].pop("@xmlns:xsi", None)
outputs['Location_V3'].pop("@xmlns:xsd", None)
outputs['Location_V3'].pop("@xmlns", None)
for key, value in outputs['Location_V3'].iteritems():
Label(swin.window, text=str(key) + " : " + str(value)).pack()
#Attempts to use the backupURL if the call to the primary URL failed
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['Location_V3']:
#loops through the response from the service and prints the values to the screen.
for key, value in outputs['Location_V3']['Error'].iteritems():
Label(swin.window, text=str(key) + " : " + str(value)).pack()
else:
#Removes unnecessary entries that were parsed into the python dictionary from XML response of service
outputs['Location_V3'].pop("@xmlns:xsi", None)
outputs['Location_V3'].pop("@xmlns:xsd", None)
outputs['Location_V3'].pop("@xmlns", None)
for key, value in outputs['Location_V3'].iteritems():
Label(swin.window, text=str(key) + " : " + str(value)).pack()
Address GeoCoder ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq "" >
<cftry>
<cfset primaryURL = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=#Address#&City=#City#&State=#State#&PostalCode=#PostalCode#&LicenseKey=#LicenseKey#">
<cfhttp url="#primaryURL#"
method="get"
result="response">
<cfset outputs = XmlParse(response.FileContent)>
<cfcatch>
<cftry>
<cfset backupURL = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=#Address#&City=#City#&State=#State#&PostalCode=#PostalCode#&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>
Address GeoCoder 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/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim backupurl As String = "https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=" + address + "&City=" + city + "&State=" + state + "&PostalCode=" + postalcode + "&LicenseKey=" + licensekey
Dim wsresponse As AGUSResponse.Location_V3 = 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
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
Address GeoCoder TSQL Rest 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">'+
'<GetBestMatch_V3 xmlns="https://www.serviceobjects.com/">'+
'<Address>' + @address + '</Address>'+
'<City>' + @City + '</City>'+
'<State>' + @State + '</State>'+
'<PostalCode>' + @postalcode + '</PostalCode>'+
'<LicenseKey>' + @key + '</LicenseKey>'+
'</GetBestMatch_V3>'+
'</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://sws.serviceobjects.com/gcr/GeoCoder.asmx', false
EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'sws.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/GetBestMatch_V3"'
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://swsbackup.serviceobjects.com/gcr/GeoCoder.asmx', false
EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'swsbackup.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/GetBestMatch_V3"'
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
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.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Configuration;
using DOTSAddressGeocodeUS.ServiceReference1;
using System.Net;
using System.Runtime.Serialization.Json;
using System.Data;
namespace DOTSAddressGeocodeUS
{
public partial class GCR_rest : System.Web.UI.Page
{
#region STATICS
static string WEB_SERVICE_PRIMARY_URL; //Included in email from Service Objects
static string WEB_SERVICE_BACKUP_URL; //Included in email from Service Objects (LIVE customers only)
static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
#endregion
protected void Page_Load(object sender, EventArgs e)
{
try
{
ErrorLabel.Visible = false;
ErrorGrid.Visible = false;
ResultGrid.Visible = false;
WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
WEB_SERVICE_PRIMARY_URL = ConfigurationManager.AppSettings["GCR_PRIMARY.GCR"];
if (string.IsNullOrWhiteSpace(WEB_SERVICE_PRIMARY_URL))
throw new System.Exception("Primary URL not set. Check your Web.config file.");
WEB_SERVICE_BACKUP_URL = ConfigurationManager.AppSettings["GCR_BACKUP.GCR"];
if (string.IsNullOrWhiteSpace(WEB_SERVICE_BACKUP_URL))
throw new System.Exception("Backup URL not set. Check your Web.config file.");
}
catch (Exception ex)
{
ErrorLabel.Visible = true;
ErrorLabel.Text = "Page load Error: " + ex.Message;
}
}
protected void btn_GO_Click(object sender, EventArgs e)
{
string address, city, state, postalCode, licenseKey;
address = inputAddress.Text;
city = inputCity.Text;
state = inputState.Text;
postalCode = inputPostalCode.Text;
licenseKey = inputLicenseKey.Text;
try
{
//NOTE: A missing parameter is not allowed
if (String.IsNullOrWhiteSpace(address))
address = " ";
if (String.IsNullOrWhiteSpace(city))
city = " ";
if (String.IsNullOrWhiteSpace(state))
state = " ";
if (String.IsNullOrWhiteSpace(postalCode))
postalCode = " ";
if (String.IsNullOrWhiteSpace(licenseKey))
licenseKey = "yourDevKey";
BestMatch_V3Response response = MakeRequest(address, city, state, postalCode, licenseKey);
ProcessResponse(response);
}
catch (Exception ex)
{
ErrorLabel.Text = ex.Message;
ErrorLabel.Visible = true;
}
}
//Creates URL and requests response from service
private static BestMatch_V3Response MakeRequest(string address, string city, string state, string postalCode, string licenseKey)
{
/*
* Due to RFC compliance, the use of URL Paths has character limitations.
* Certain characters are invalid and cause HTTP Errors; these characters
* include #, /, ?, as well as some high bit characters.
*
* If you suspect that this may be an issue for you then it is recommended to change your
* request from the URL path parameter format to the query string parameter format.
* Example:
* FROM {data}/{data2}/{key}?format=json
* TO parameter1={data1}¶meter2={data2}&licensekey={key}
* Another alternative is to use HTTP Post instead of HTTP Get.
*/
BestMatch_V3Response result = null;
string mainURL = WEB_SERVICE_PRIMARY_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
string backupURL = WEB_SERVICE_BACKUP_URL + address + "/" + city + "/" + state + "/" + postalCode + "/" + licenseKey + "?format=json";
try
{
result = HttpGet(mainURL);
//NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP
if (result == null || (result.Error != null && result.Error.Number == "3"))
{
return HttpGet(backupURL);
}
else
{
return result;
}
}
catch (Exception e)
{ //ERROR IN MAIN URL - USING BACKUP
return HttpGet(backupURL);
}
}
//HTTP Get Method and parse into user-defined object
private static BestMatch_V3Response HttpGet(string requestUrl)
{
try
{
//NOTE: URL encoding occurs automatically when creating the web request
HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
request.Timeout = WEB_SERVICE_REQUEST_TIMEOUT;//timeout for get operation
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
if (response.StatusCode != HttpStatusCode.OK)
throw new Exception(String.Format(
"Server error (HTTP {0}: {1}).",
response.StatusCode,
response.StatusDescription));
//parse response
DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(BestMatch_V3Response));
object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
BestMatch_V3Response jsonResponse = objResponse as BestMatch_V3Response;
return jsonResponse;
}
}
catch (Exception e)
{
throw e;
}
}
//Process the returned user-defined object
private void ProcessResponse(BestMatch_V3Response response)
{
try
{
//processing result
if (response.Error == null)
{
ProcessResult(response);
}
//processing error
else
{
ProcessError(response.Error);
}
}
catch (Exception e)
{
throw e;
}
}
//Process and display the result values
private void ProcessResult(BestMatch_V3Response result)
{
try
{
DataTable dtProvider = new DataTable();
dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
dtProvider.Rows.Add("Latitude", result.BestMatchInfo.Latitude);
dtProvider.Rows.Add("Longitude", result.BestMatchInfo.Longitude);
dtProvider.Rows.Add("Zip", result.BestMatchInfo.Zip);
dtProvider.Rows.Add("Tract", result.BestMatchInfo.Tract);
dtProvider.Rows.Add("Block", result.BestMatchInfo.Block);
dtProvider.Rows.Add("Level", result.BestMatchInfo.Level);
dtProvider.Rows.Add("LevelDescription", result.BestMatchInfo.LevelDescription);
dtProvider.Rows.Add("StateFIPS", result.BestMatchInfo.StateFIPS);
dtProvider.Rows.Add("CountyFIPS", result.BestMatchInfo.CountyFIPS);
dtProvider.Rows.Add("Debug", result.BestMatchInfo.Debug);
ResultGrid.Visible = true;
ErrorGrid.Visible = false;
ResultGrid.DataSource = new DataView(dtProvider);
ResultGrid.DataBind();
}
catch (Exception e)
{
throw e;
}
}
//Process and display the error values
private void ProcessError(Error error)
{
try
{
DataTable dtError = new DataTable();
//A case statement is used here because it is often useful to do different
//things depeneding on which general type of error occurs.
//Handle the errors according to your production needs.
switch (System.Convert.ToInt32(error.Number))
{
case 1:
//Authorization Error
break;
case 2:
//User Input Error
break;
case 4:
//Domain Specific Error
break;
default:
//default (error code 3) Service Objects Fatal Error Error
break;
}
dtError.Columns.Add(new DataColumn("Output", typeof(string)));
dtError.Columns.Add(new DataColumn("Values", typeof(string)));
dtError.Rows.Add("Desc", error.Desc);
dtError.Rows.Add("Number", error.Number);
dtError.Rows.Add("Location", error.Location);
ResultGrid.Visible = false;
ErrorGrid.Visible = true;
ErrorGrid.DataSource = new DataView(dtError);
ErrorGrid.DataBind();
}
catch (Exception e)
{
throw e;
}
}
}
}
- GetZipInfo
- GetGeoLocation
- GetDistanceToWaterByAddress
- GetLocationByCityState
- GetDistance
- GetBestMatch_V3
- GetGeoLocationByZipPlusTwo
- GetReverseLocation
- GetGeoLocationByZipPlusFour
- GetDistanceToWater
- GetGeoLocationWorldwide
GetZipInfo Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetZipInfo?PostalCode=93117&LicenseKey=yourDevKey
XML Response
<ZipInfoResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ZipInfo>
<City>GOLETA</City>
<State>CA</State>
<County>SANTA BARBARA</County>
<AreaCode>805</AreaCode>
<CityAbbreviation>GAVIOTA</CityAbbreviation>
<CityType>N</CityType>
<CountyFIPS>083</CountyFIPS>
<StateFIPS>06</StateFIPS>
<TimeZone>8</TimeZone>
<DayLightSavings>Y</DayLightSavings>
<MSA>7480</MSA>
<Md/>
<CBSA>42200</CBSA>
<PMSA/>
<DMA>Santa Barbara - Santa Maria - San Luis Obispo</DMA>
<Latitude>34.511736</Latitude>
<Longitude>-120.062476</Longitude>
<Zip>93117</Zip>
<CityAlternativeName xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a:string>SANTA BARBARA</a:string>
<a:string>ISLA VISTA</a:string>
<a:string>GAVIOTA</a:string>
<a:string>GOLETA</a:string>
</CityAlternativeName>
</ZipInfo>
</ZipInfoResponse>
GetGeoLocation Example Request and Response
<GeoLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GeoLocationInfo>
<Latitude>34.418014</Latitude>
<Longitude>-119.696477</Longitude>
<Zip>93101-7603</Zip>
<Tract>0009.00</Tract>
<Block>2039</Block>
<Level>S</Level>
</GeoLocationInfo>
</GeoLocationResponse>
GetDistanceToWaterByAddress Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistanceToWaterByAddress?Address=27+E+Cota&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey
XML Response
<WaterLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<WaterLocationInfo>
<MilesToWater>0.605</MilesToWater>
<Latitude>34.418014</Latitude>
<Longitude>-119.696477</Longitude>
<ClosestWaterLatitude>34.413116</ClosestWaterLatitude>
<ClosestWaterLongitude>-119.687683</ClosestWaterLongitude>
</WaterLocationInfo>
</WaterLocationResponse>
GetLocationByCityState Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByCityState?City=Santa+Barbara&State=CA&LicenseKey=yourDevKey
XML Response
<GeoLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GeoLocationInfo>
<Latitude>34.4488</Latitude>
<Longitude>-119.733</Longitude>
</GeoLocationInfo>
</GeoLocationResponse>
GetDistance Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistance?FromLatitude=37.668044&FromLongitude=-121.769621&ToLatitude=34.414106&ToLongitude=-119.860635&LicenseKey=yourDevKey
XML Response
<DistanceResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<DistanceInfo>
<MilesBetween>249.096</MilesBetween>
<KilometersBetween>400.881</KilometersBetween>
<FeetBetween>1315227</FeetBetween>
</DistanceInfo>
</DistanceResponse>
GetBestMatch_V3 Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetBestMatch_V3?Address=27+E+Cota&City=Santa+Barbara&State=CA&PostalCode=93101&LicenseKey=yourDevKey
XML Response
<BestMatch_V3Response xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<BestMatchInfo>
<Latitude>34.418014</Latitude>
<Longitude>-119.696477</Longitude>
<Zip>93101-7603</Zip>
<Tract>0009.00</Tract>
<Block>2039</Block>
<Level>S</Level>
<LevelDescription>
The address matched exactly at the property location.
</LevelDescription>
<StateFIPS>06</StateFIPS>
<CountyFIPS>083</CountyFIPS>
<Debug/>
</BestMatchInfo>
</BestMatch_V3Response>
GetGeoLocationByZipPlusTwo Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByZipPlusTwo?PostalCode=9311723&LicenseKey=yourDevKey
XML Response
<GeoLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GeoLocationInfo>
<Latitude>34.442159</Latitude>
<Longitude>-119.823612</Longitude>
</GeoLocationInfo>
</GeoLocationResponse>
GetReverseLocation Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetReverseLocation?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey
XML Response
<ReverseLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReverseLocationInfo>
<Address>118 E DE LA GUERRA ST</Address>
<City>SANTA BARBARA</City>
<State>CA</State>
<Zip>93101</Zip>
<County>SANTA BARBARA</County>
</ReverseLocationInfo>
</ReverseLocationResponse>
GetGeoLocationByZipPlusFour Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationByZipPlusFour?PostalCode=931172323&LicenseKey=yourDevKey
XML Response
<GeoLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GeoLocationInfo>
<Latitude>34.442415</Latitude>
<Longitude>-119.821683</Longitude>
</GeoLocationInfo>
</GeoLocationResponse>
GetDistanceToWater Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetDistanceToWater?Latitude=34.421556&Longitude=-119.697222&LicenseKey=yourDevKey
XML Response
<WaterLocationResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<WaterLocationInfo>
<MilesToWater>0.787</MilesToWater>
<Latitude>34.421556</Latitude>
<Longitude>-119.697222</Longitude>
<ClosestWaterLatitude>34.413002</ClosestWaterLatitude>
<ClosestWaterLongitude>-119.688103</ClosestWaterLongitude>
</WaterLocationInfo>
</WaterLocationResponse>
GetGeoLocationWorldwide Example Request and Response
URL Request: https://trial.serviceobjects.com/gcr/GeoCoder.asmx/GetGeoLocationWorldwide?City=Santa+Barbara&Region=&Country=USA&LicenseKey=yourDevKey
XML Response
<ArrayOfGeoLocationWorldwideResponse xmlns="https://serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<GeoLocationWorldwideResponse>
<GeoLocationWorldwideInfo>
<City>Santa Barbara</City>
<Region>California</Region>
<Country>United States</Country>
<Latitude>34.4119</Latitude>
<Longitude>-119.7280</Longitude>
</GeoLocationWorldwideInfo>
</GeoLocationWorldwideResponse>
</ArrayOfGeoLocationWorldwideResponse>
List of Operations
GetbestMatch_V4 – Returns the latitude and longitude for a given US Address, along with additional location information. NOTICE: This operation is currently restricted to trial (beta) use only.
GetGeoLocationByZipPlusFour – Returns latitude/longitude location information for a given zip plus four (99999-9999)
GetGeoLocationByZipPlusTwo – Returns latitude/longitude location information for a given zip plus two (99999-99)
GetGeoLocationByCityState – Returns latitude/longitude location information for a given city and state. Returns data as close to the city centroid as possible.
GetZipInfo – Returns extensive and various information about a given zip code, including census information and centroid latitude/longitude coordinates.
GetDistance – Returns an estimated distance between two given locations.
GetDistanceToWater – Returns an estimated distance from a given latitude and longitude to the nearest saltwater.
GetDistanceToWaterByaddress – Returns an estimated distance from a given address to the nearest saltwater.
GetGeolocationWorldwide – Returns Lat Lon information for a given worldwide city. Multiple matches can be filtered by country or region(state, province etc.)
GetReverseLocation – Returns an estimated address for a given latitude and longitude.
GetGeoLocation – (Deprecated: use GetBestMatch_V3)
GetBestMatch – (Deprecated: use GetBestMatch_V3)
GetBestMatch_V2 – (Deprecated: use GetBestMatch_V3)
Operation Definitions
Every geocoding system is different, and some even use different standards for gathering and calculating coordinates. Because of this, using coordinates from one system may not look to be at the exact location on a different system. For example, Google Maps is a great tool for plotting geocoding coordinates on a viewable map. However, the data used for generating these maps is different than the data that Service Objects uses for generating geocoding coordinates. Thus, some points plotted on Google Maps may not look to be in the precise location; they may look exactly right or look to be several hundred feet away.
GetBestMatch_V3
GetBestMatch_V3 tries to find a match at the most granular level that it can:
- Property Match on the street level
- Zip + 4 Match
- Zip + 3 Match
- Zip + 2 Match
- Zip + 1 Match
- Zip Match
- City/State Match (least accurate)
This operation will also return a code indicating the level at which it matched. The codes are:
P – Zip plus four match
R – Zip plus three match
T – Zip plus two match
N – Zip plus one match
Z – Zip level match (zip plus zero)
C – City/state match
GetBestMatch_V3 Inputs
| Name | Type | Description |
|---|---|---|
| Address | String | Address line of the address to geocode. For example, “123 Main Street”. |
| City | String | The city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to geocode. For example, “NY”. This does not need to be contracted, full state names will work as well.The state isn’t required, but if one is not provided, the Zip code is required. |
| PostalCode | String | The zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetBestMatch_V3 Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given address. |
| Longitude | String | Number | The longitude of the given address. |
| Tract | String | Number | The census tract of the given address. A census tract is a statistical subdivision of a county. |
| Block | String | Number | The census block of the given address. A block is the smallest geographic unit used by the US Census. |
| Zip | String | Varies | The corrected zip plus four of the given address. |
| Level | String | Varies, see above | The level code at which the address matched. See above for a listing of possible outputs. |
| LevelDescription | String | Varies | An explicit description of the level code, described above. |
| StateFIPS | String | Two digits | State FIPS(Federal Information Processing Standard) code; used to uniquely identity states . |
| CountyFIPS | String | Three digits | County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetBestMatch_V4
| This operation is currently restricted to Trial (beta) use only. |
HTTP GET Request URL Formats
HTTP POST Request Help Page
SOAP URL
Service XML Request Help Page
Service JSON Request Help Page
GetBestMatch_V4 tries to find a match at the most granular level that it can:
- Property Match on the street level
- Zip + 4 Match
- Zip + 3 Match
- Zip + 2 Match
- Zip + 1 Match
- Zip Match
- City/State Match (least accurate)
This operation will also return a code indicating the level at which it matched. The codes are:
P – Zip plus four match
R – Zip plus three match
T – Zip plus two match
N – Zip plus one match
Z – Zip level match (zip plus zero)
C – City/state match
GetBestMatch_V4 Inputs
| Name | Type | Description |
|---|---|---|
| Address | String | Address line of the address to geocode. For example, “123 Main Street”. |
| City | String | The city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to geocode. For example, “NY”. This does not need to be contracted, full state names will work as well.The state isn’t required, but if one is not provided, the Zip code is required. |
| PostalCode | String | The zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetBestMatch_V4 Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Level | String | Varies | The level code at which the address matched. See above for a listing of possible outputs. |
| LevelDescription | String | Varies | An explicit description of the level code, described above. |
| Latitude | String | Decimal Number | The latitude of the given address. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. |
| Longitude | String | Decimal Number | The longitude of the given address. A decimal number up to 10 digits with a max precision of up to 7 places after the decimal point. |
| Zip | String | Varies | The corrected zip plus four of the given address. |
| InformationComponents | InformationComponent array or NULL | Varies | A name-value pair collection containing additional information about the location. See the InformationComponent table and the list of Components for more details. |
InformationComponent
| Name | Type | Values | Description |
|---|---|---|---|
| Name | String | Varies | The component name of the Name-Value pair. Possible examples are “CountyFIPS”, “CensusTract” “CensusGeoID” |
| Value | String | Varies | The component value of the Name-Value pair. |
Current List of Components
| Name | Type | Values | Description |
|---|---|---|---|
| StateFIPS | String | 2 Digit Number | State FIPS(Federal Information Processing Standard) code; used to uniquely identity states . |
| CountyFIPS | String | 3 Digit Number | County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US. |
| CensusTract | String | 6 Digit Decimal Number | The census tract of the given address. A census tract is a statistical subdivision of a county. |
| CensusBlock | String | 4 Digit Number | The census block of the given address. A block is the smallest geographic unit used by the US Census. |
| CensusGeoID | String | 15 Digit Number | A Census based geographic identification code that uniquely identifies a geographic statistical area. |
| ClassFP | String | Alpha-Numeric | A code that defines the current class of the geographic location. |
| SLDUST | String | Varies | Current state legislative district upper (senate) chamber code. |
| SLDLST | String | Varies | Current state legislative district lower (house) chamber code |
Current List of ClassFP Codes
| ClassFP Code | Class Code Description | Associated Geographic Entity |
|---|---|---|
| C1 | An active incorporated place that does not serve as a county subdivision equivalent | Economic Census Place, Incorporated Place |
| C2 | An active incorporated place that is legally coextensive with a county subdivision but treated as independent of any county subdivision | County Subdivision, Economic Census Place, Incorporated Place |
| C3 | Consolidated City | Consolidated City |
| C4 | Alternate official common name for an incorporated place | Locality Point |
| C5 | An active incorporated place that is independent of any county subdivision and serves as a county subdivision equivalent | County Subdivision, Economic Census Place, Incorporated Place |
| C6 | An active incorporated place that partially is independent of any county subdivision and serves as a county subdivision equivalent or partially coextensive with a county subdivision but treated as independent of any county subdivision | Incorporated Place |
| C7 | An incorporated place that is independent of any county | County or Equivalent Feature, County Subdivision, Economic Census Place, Incorporated Place |
| C8 | The balance of a consolidated city excluding the separately incorporated place(s) within that consolidated government | Economic Census Place, Incorporated Place |
| C9 | An inactive or nonfunctioning incorporated place | Economic Census Place, Incorporated Place |
| M1 | A military or other defense installation that is not entirely within a census designated place | Locality Point, Military Installation |
| M2 | A military or other defense installation entirely within a place | Census Designated Place, Economic Census Place, Military Installation |
| U1 | A census designated place with an official federally recognized name | Census Designated Place, Economic Census Place |
| U2 | A census designated place without an official federally recognized name | Census Designated Place, Economic Census Place |
GetGeoLocationByZipPlusFour
GetGeoLocationByZipPlusFour Inputs
| Name | Type | Description |
|---|---|---|
| Zip | String | The zip plus four to geocode. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetGeoLocationByZipPlusFour Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given zip plus four. |
| Longitude | String | Number | The longitude of the given zip plus four. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetGeoLocationByZipPlusTwo
GetGeoLocationByZipPlusTwo Inputs
| Name | Type | Description |
|---|---|---|
| Zip | String | The zip plus four to geocode. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetGeoLocationByZipPlusTwo Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given zip plus four. |
| Longitude | String | Number | The longitude of the given zip plus four. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetZipInfo
GetZipInfo Inputs
| Name | Type | Description |
|---|---|---|
| Zip | String | The zip plus four to geocode. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetZipInfo Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| City | String | Varies | The city of the given zip code. Alternate city names are given below. |
| State | String | Varies | The state of the given zip code. |
| County | String | Varies | The county of the given zip code. |
| AreaCode | String | Varies | The area code of the given zip code. |
| CityAbbreviation | String | Varies | A common abbreviation of the city name of the given zip code. |
| CityType | String | N, P, U, B, A, C, S, K | The city type of the given zip code. The city type of the given zip code. The code refers to the type of postal station in a given zip code. See table below for descriptions for each of the codes. |
| CountyFIPS | String | Number | County FIPS(Federal Information Processing Standard) code; used to uniquely identify counties across the US. |
| StateFIPS | String | Number | State FIPS(Federal Information Processing Standard) code; used to uniquely identity states . |
| TimeZone | String | Number | The number of hours offset from GMT. 5 = Eastern time zone. |
| DayLightSavings | String | Y or N | Whether the given zip code observes Day Light Savings time. |
| MSA | String | Varies | The Metropolitan Statistical Area Code. Used to uniquely identify a geographic area with a relatively high population density at its core. |
| MD | String | Varies | The Metropolitan District Code. |
| CBSA | String | Varies | The Core Based Statistical Area Code. A code used to identify an urban center of at least 10,000 people and adjacent areas that are socioeconomically tied to the urban center. |
| PMSA | String | Varies | The Primary Metropolitan Statistical Area code. Used to uniquely identify areas that are part of a larger urban center. |
| DMA | String | Varies | The Designated Market Area code. Used to uniquely identify a geographic region that receive the same(or similar) TV and radio show programs. |
| Latitude | String | Number | The latitude centroid of the given zip code. |
| Longitude | String | Number | The longitude centroid of the given zip code. |
| Zip | String | Varies | The zip code input. |
| CityAlternativeName | ArrayOfString | Varies | A list of strings that contain alternate names for the city of the given zip code. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
CityType Code Definitions
| Code | Description |
|---|---|
| N | Non Postal Community Name: Former Postal Facility |
| P | Post Office: An official post office branch. |
| U | Urbanization: A postal designation specific to Puerto Rico. |
| B | Branch: A postal facility that is not the main post office and is outside the corporate limits of a city. |
| A | Airport Mail Facility: Facilities through which US mail is flown in and out of a city. |
| C | Community Post Office: a contract postal unit providing mail services to small communities. |
| S | Station: A post office that is not the main office for a city but is in corporate city limits. |
| K | Bulk Mail Center: Centers that handle bulk mail. Typically commercial, business and advertising mail. |
GetGeoLocationByCityState
GetGeoLocationByCityState Inputs
| Name | Type | Description |
|---|---|---|
| City | String | The city to geocode. |
| State | String | The State to geocode. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetGeoLocationByCityState Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given zip plus four. |
| Longitude | String | Number | The longitude of the given zip plus four. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetDistance
GetDistance Inputs
| Name | Type | Description |
|---|---|---|
| FromLatitude | String | The latitude for location A. |
| FromLongitude | String | The longitude for location A. |
| ToLatitude | String | The latitude for location B. |
| ToLongitude | String | The longitude for location B. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ Accepts 9 digit long decimal degree coordinates with a precision of up to 6 decimal places. |
GetDistance Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| MilesBetween | String | Decimal Number | An estimate on the number of miles between the two coordinate locations. |
| KilometersBetween | String | Decimal Number | An estimate on the number of kilometers between the two coordinate locations. |
| FeetBetween | String | Number | An estimate on the number of feet between the two coordinate locations. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetDistanceToWater
GetDistanceToWater Inputs
| Name | Type | Description |
|---|---|---|
| Latitude | String | The latitude of the location. |
| Longitude | String | The longitude of the location. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetDistanceToWater Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| MilesToWater | String | Decimal Number | An estimate on the number of miles between the given location and the nearest saltwater. |
| Latitude | String | Decimal Number | The latitude of the location. |
| Longitude | String | Decimal Number | The longitude of the location. |
| ClosestWaterLatitude | String | Decimal Number | The longitude of the closest saltwater location. |
| ClosestWaterLongitude | String | Decimal Number | The longitude of the closest saltwater location. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetDistanceToWaterByaddress
GetDistanceToWaterByaddress Input
| Name | Type | Description |
|---|---|---|
| Address | String | The address of the location. |
| City | String | The city of the the location. |
| State | String | The state of the location. |
| PostalCode | String | The postal code of the location. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetDistanceToWaterByaddress Output
| Name | Type | Values | Description |
|---|---|---|---|
| MilesToWater | String | Decimal Number | An estimate on the number of miles between the given location and the nearest saltwater. |
| Latitude | String | Decimal Number | The latitude of the location. |
| Longitude | String | Decimal Number | The longitude of the location. |
| ClosestWaterLatitude | String | Decimal Number | The Latitude of the closest saltwater location. |
| ClosestWaterLongitude | String | Decimal Number | The longitude of the closest saltwater location. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetGeoLocationWorldwide
GetGeoLocationWorldwide Inputs
| Name | Type | Description |
|---|---|---|
| City | String | The city to geocode. This is a required input parameter. |
| Region | String | The region (state, province etc.) of the city to geocode. |
| Country | String | The Country of the city to geocode. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/ |
GetGeoLocationWorldwide Outputs
| Name | Type | Value | Description |
|---|---|---|---|
| City | String | Varies | The name of the city. |
| Region | String | Varies | The region associated with the city. |
| Country | String | Varies | The country associated with the city. |
| Latitude | String | Decimal Number | The latitude centroid of the city. |
| Longitude | String | Decimal Number | The longitude centroid of the city. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetReverseLocation
GetReverseLocation Inputs
| Name | Type | Description |
|---|---|---|
| Latitude | String | The latitude of the location. |
| Longitude | String | The longitude of the location. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetReverseLocation Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Address | String | Varies | The estimated address of the given coordinates. |
| City | String | Varies | The city of the given coordinates. |
| State | String | Varies | The state of the given coordinates. |
| Zip | String | Varies | The zip of the given coordinates. |
| County | String | Varies | The county of the given coordinates. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetGeoLocation
| Name | Type | Description |
|---|---|---|
| Address | String | Address line of the address to geocode. For example, “123 Main Street”. |
| City | String | The city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to geocode. For example, “NY”. This does not need to be contracted, full state names will work as well.The state isn’t required, but if one is not provided, the Zip code is required. |
| Zip | String | The zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetGeoLocation Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given address. |
| Longitude | String | Number | The longitude of the given address. |
| Tract | String | Number | The census tract of the given address. A census tract is a statistical subdivision of a county. |
| Block | String | Number | The census block of the given address. A block is the smallest geographic unit used by the US Census. |
| Zip | String | Varies | The corrected zip plus four of the given address. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetBestMatch
- Street Level Match (most accurate; property-level match)
- Zip + 4 Match
- Zip + 2 Match
- Zip Match
- City/State Match(least accurate)
P – Zip plus four match
T – Zip plus two match
Z – Zip level match (zip plus zero)
C – City/state match
GetBestMatch Inputs
| Name | Type | Description |
|---|---|---|
| Address | String | Address line of the address to geocode. For example, “123 Main Street”. |
| City | String | The city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to geocode. For example, “NY”. This does not need to be contracted, full state names will work as well.The state isn’t required, but if one is not provided, the Zip code is required. |
| Zip | String | The zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetBestMatch Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given address. |
| Longitude | String | Number | The longitude of the given address. |
| Tract | String | Number | The census tract of the given address. |
| Block | String | Number | The census block of the given address. |
| Zip | String | Varies | The corrected zip plus four of the given address. |
| Level | String | Varies, see above | The level code at which the address matched. See above for a listing of possible outputs. |
| LevelDescription | String | Varies | An explicit description of the level code, described above. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
GetBestMatch_V2
- Street Level Match (most accurate; property-level match)
- Zip + 4 Match
- Zip + 3 Match
- Zip + 2 Match
- Zip + 1 Match
- Zip Match
- City/State Match (least accurate)
P – Zip plus four match
R – Zip plus three match
T – Zip plus two match
N – Zip plus one match
Z – Zip level match (zip plus zero)
C – City/state match
GetBestMatch_V2 Inputs
| Name | Type | Description |
|---|---|---|
| Address | String | Address line of the address to geocode. For example, “123 Main Street”. |
| City | String | The city of the address to geocode. For example, “New York”. The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to geocode. For example, “NY”. This does not need to be contracted, full state names will work as well.The state isn’t required, but if one is not provided, the Zip code is required. |
| Zip | String | The zip code of the address to geocode. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com |
GetBestMatch_V2 Outputs
| Name | Type | Values | Description |
|---|---|---|---|
| Latitude | String | Number | The latitude of the given address. |
| Longitude | String | Number | The longitude of the given address. |
| Tract | String | Number | The census tract of the given address. |
| Block | String | Number | The census block of the given address. |
| Zip | String | Varies | The corrected zip plus four of the given address. |
| Level | String | Varies, see above | The level code at which the address matched. See above |
| for a listing of possible outputs. | |||
| LevelDescription | String | Varies | An explicit description of the level code, described above. |
| 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. |
| Error – Location | String | Always null | Deprecated, no longer used. |
Error Codes
| <GetGeoLocation xmlns=”https: //www. serviceobjects .com/”> |
The namespace is not applied to the GetGeoLocation element, it is only present.
| Desc. Code | Description |
| 2 | Address field was too long, must be 300 characters or less. |
| 2 | Both a latitude and longitude are required. Please check your input and try again. |
| 2 | Invalid Postal Code |
| 2 | Latitude and longitude must be numeric. Please check your input and try again. |
| 2 | Latitude and longitude values must be numeric. |
| 2 | Latitude and longitude values are required for both locations. |
| 2 | Latitude and Longitude were not found for this address. Please check your input and try again. |
| 2 | Latitude values must be between -90 and 90 degrees. |
| 2 | Lat/Long value is not near water. |
| 2 | Location not found. |
| 2 | No address found. |
| 2 | Address was not found. |
| 2 | Longitude values must be between -180 and 180 degrees. |
| 2 | Please enter at least the first 2 letters of the city name. |
| 2 | Please input a city and state. |
| 2 | Please input a street address. |
| 2 | Please input a valid US Zip Code. |
| 2 | Please input either zip code or both city and state. |
| 2 | Please input zip code plus four. |
| 2 | Please input zip code plus four. |
| 2 | Please input zip code plus two. |
| 2 | Please input zip code plus two. |
| 2 | Please provide a valid license key for this web service. |
| 2 | Zip code does not exist. |
Error Code 4 – “Various Descriptions”
| Desc. Code | Description |
| 4 | Address could not be found, search timed out. |
| 4 | Error initializing service. |
| 4 | Internal Error. Please contact customer service. |
Frequently Asked Questions
Which Operation Should You Use? GetGeoLocation or GetBestMatch_V3?
The Sample Code is Giving Strange Errors or is Crashing!
https://trial.serviceobjects.com/gcr/GeoCoder.asmx
Contact your systems administrator to resolve why you are not able to connect to Service Objects.
DOTS Address Geocode – US says it can’t find my address!
DOTS Address Geocode – US is giving coordinates that aren’t anywhere near my address!
No Census tract or block data was returned for a street level match.
I’m Not a Programmer. How Do I Use DOTS Address Geocode – US?
Do you also provide a RESTful interface?
Conclusion
https://www.serviceobjects.com/address-geocode/