- Introduction
- Integration
- List of Operations
- Operation Definitions
- Error Codes
- Frequently Asked Questions
- Conclusion
Introduction
DOTS Address Geocode – US is a publicly available XML web service that provides latitude/longitude and metadata information about a physical US address. The service provides geocoding information, such as the latitude and longitude location of a US address, along with demographic information, such as the census tract, block and other metadata.
DOTS Address Geocode – US can help provide instant address locations to websites or enhancement to contact lists.
Integration
Integrating DOTS Address Geocode – US 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/sample-code/?service=34
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 complex business logic. Web services are too large 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.
DOTS Address Geocode – US 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/gcr/GeoCoder.asmx
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/gcr/GeoCoder.asmx?WSDL
Important Note!
SOAP is done via POST, only with special XML markup in the post-body.
This XML is the definition of the web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another 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 DOTS Address Geocode – US, you can provide this one.
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
- 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_V3 – Returns latitude, longitude, tract, block, state FIPS, county FIPS, and ZIP+4 if available. Will attempt to geocode at the property level, zip+4 level, zip+3, zip+2, zip+1, zip, and city/state. (Recommended operation)
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
This document defines the input, output and behavior of the web service operations in DOTS Address Geocode – US. Each operation has its own unique behavior and output, though some of the operations are very similar.
Important Note!
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.
You should examine your own business needs first before exploring what DOTS Address Geocode – US can provide. Different operations may be necessary based on the information you have, and the granularity of data you need.
GetBestMatch_V3
This operation is identical to GetBestMatch_V2, but additionally returns state and county FIPS codes.
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:
S – Street Level Property Match
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
Returns the latitude and longitude for a given US address. This operation will use cascading logic when an exact address match is not found and it will return the next closest level match available. The operation output is designed to allow the service to return new pieces of data as they become available without having to re-integrate.
This operation is currently restricted to Trial (beta) use only. |
HTTP GET Request URL Formats
HTTP POST Request Help Page
XML: https://trial.serviceobjects.com/gcr/api.svc/xml/help/operations/GetBestMatch_V4_POST
JSON: https://trial.serviceobjects.com/gcr/api.svc/json/help/operations/GetBestMatch_V4_POST
SOAP URL
WSDL: https://trial.serviceobjects.com/gcr/soap.svc?wsdl
Service XML Request Help Page
https://trial.serviceobjects.com/gcr/api.svc/xml/help
Service JSON Request Help Page
https://trial.serviceobjects.com/gcr/api.svc/json/help
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:
S – Street Level Property Match
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
This operation is almost exactly like GetGeoLocation, but rather than geocoding given a specific address, DOTS Address Geocode – US will geocode given a zip plus four. The coordinates given are an average centroid of a given zip plus four region and oftentimes match precisely to the street location.
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
This operation is almost exactly like GetGeoLocationByZipPlusFour, but instead uses only a Zip plus two. If a zip plus four is provided, this operation will geocode only using the subset zip plus two.
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
This operation provides valuable information about a specific zip code. Included are many demographics codes that many users find valuable for tracking customers and statistical analysis.
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
This operation is almost exactly like GetGeoLocationByZipPlusFour, but rather than geocoding given a zip plus four, DOTS Address Geocode – US will geocode given a city and state. The coordinates given are an average centroid of the entire city.
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
This operation returns an estimate on the number of miles, kilometers and feet between two sets of coordinates.
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
Returns an estimated distance from a given latitude and longitude to the nearest saltwater.
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
Returns an estimated distance from a given address to the nearest saltwater.
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
Returns Lat Lon information for a given worldwide city. Multiple matches can be filtered by country or region(state, province etc.)
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
This operation is capable of returning multiple matches. All matches are contained in a GetGeoLocationWorldwideResult object. The GetGeoLocationWorldwideResult object returns a list of GeocodeCityWorldwideInfo objects.
GeocodeCityWorldwideInfo
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
Returns an estimated address for a given latitude and longitude.
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
This is the basic operation for finding the latitude/longitude coordinates of an address. This operation takes a standard US address (Address, City, State, Zip) and will try to find the exact street location’s coordinates. It cannot always find the location, especially when it comes to empty lots or new construction areas.
This operation will also return census tract and block, if available, for the given address. This data is valuable for tracking demographics and statistical analysis. If a valid zip code is found for the given address, it will be returned as well.First, DOTS Address Geocode – US will attempt to correct and normalize the address to make it more likely to geocode properly. You don’t need to worry about fixing the address before sending it to DOTS Address Geocode – US, unless you want to filter out invalid or non-existent addresses beforehand. This operation requires the Address value, and either City and State, or the Zip code. Providing all inputs is recommended.
GetGeoLocation 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 |
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
Often, users want to geocode as best we can – if we can’t match an address exactly at the street level, they’d like it at the zip plus four level, and if not at zip plus four, then at zip plus two, and so on.
The GetBestMatch operation does exactly that; it tries to find a match at the most granular level that it can:
- Street Level Match (most accurate; property-level match)
- Zip + 4 Match
- Zip + 2 Match
- Zip Match
- City/State Match(least accurate)
This operation will also return the level at which it matched. The codes are:
S – Street/exact match (property-level match)
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
This operation is identical to GetBestMatch, but additionally will attempt to match at the Zip + 3 and Zip + 1 levels.
GetBestMatch_V2 tries to find a match at the most granular level that it can:
- 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)
This operation will also return the level at which it matched. The codes are:
S – Street/exact match (property-level match)
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
Error codes in DOTS Address Geocode – US 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 https://www.serviceobjects.com namespace on the root ValidateEmail element as so:
<GetGeoLocation xmlns=”https: //www. serviceobjects .com/”> |
Important Note!
The namespace is not applied to the GetGeoLocation 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.
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”
An error code 4 is a fatal error and it means something has seriously gone wrong. You will never see an error code 4 in a live production environment.
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?
Picking which operation you want to use should be decided carefully. Depending on your environment and needs, you will need to use different operations for their corresponding strengths.If you always need precise location coordinates, then stick with GetGeoLocation. The other operations won’t give you the detail you’re looking for. If your application does not require precise coordinate location, but will work with general-area mapping, GetBestMatch_V3 will give you a much higher match count than GetGeoLocation alone. The best suggestion is to try out each of the operations to find the data you need.
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/gcr/GeoCoder.asmx
Then 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 isn’t able to connect either.
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 doesn’t know about every address, especially empty lots or new streets. Often, it won’t be able to find coordinates to these locations. We do our best to try to improve the data as often as possible. However, it will often be able to match a zip plus four or zip plus two. If it cannot match the exact street location, try the GetBestMatch operation to find how close it can find your data.We are constantly striving to improve our data! DOTS Address Geocode – US may not be able to find your location now, but may in the future as we improve our databases.
DOTS Address Geocode – US is giving coordinates that aren’t anywhere near my address!
If you are using the GetBestMatch operation, most likely the service is matching at Zip+4, Zip+2, or Zip level, which return an averaged centroid. The service isn’t saying your address is at that location, it is saying the centroid of the zip/+4/+2 is at that location.If DOTS Address Geocode – US is giving what it says is a street-level match that doesn’t look like it’s at the right location plotted on a map, the issue is most often a stylistic difference between your mapping solution and our data. Because geocoding information is gathered in very different ways, your mapping solution is probably using a very different method than Service Objects does. If the location given is a street-level match, and it’s very far away from the target location, please let us know at support@serviceobjects.com
No Census tract or block data was returned for a street level match.
The geocoding service makes use of multiple data sources and the census data is disparate from the coordinate datasets. There is not always a one to one match for the two, so the census tract and block code will not always be available. Cases for this should be very rare overall, but it may be more noticeable for some rural areas or new developments. If you encounter this issue then please contact support@serviceobjects.com with one or more example addresses so that we can investigate.
I’m Not a Programmer. How Do I Use DOTS Address Geocode – US?
Service Objects runs batches for you! A free batch trial is available at https://www.serviceobjects.com/upload-center/.
Do you also provide a RESTful interface?
Yes we do! For more information on how to use our RESTful interface go here DOTS Address Geocode – US – REST.
Conclusion
Service Objects is proud to offer you a free trial of DOTS Address Geocode – US.
Sign up today for a free trial at:
https://www.serviceobjects.com/address-geocode/
Other technical questions or concerns can be directed to support@serviceobjects.com
If you are interested in purchasing DOTS Address Geocode – US, please contact sales@serviceobjects.com.