Reference Guide

Reference Guide#

Introduction #

The WebSmart GeoCoder returns geographic, demographic and census data for a given location, defined by the address key returned by the Address Verifier service (or a postal code for Canadian addresses).

The GeoCoder Service:

Returns the latitude and longitude (U.S. and Canada).
Returns the time zone (U.S. and Canada).
Returns FIPS County information Place Code, Census Block and Census Tract and Core Based Statistical Area (U.S. only).

An option of GeoCoder, GeoPoint uses multisource data to return latitude and longitude coordinates down to the rooftop of over 95% of all physical addresses in the United States.

There are two levels of accuracy within GeoPoint:

Rooftop - The most accurate latitude and longitude available with coverage of approximately 75 million individual addresses.
Interpolated Rooftop - These coordinates are computed using mathematical algorithms and street shape maps. While these coordinates are educated estimates, they should be quite accurate for the majority of the United States. There may be cases where the location of interpolated points is not very near the actual residence, mostly in rural areas with long streets and non-standard house numbering. However, these coordinates are still much more accurate than ZIP + 4 coordinates.

Service URLs #

Protocol	URL
SOAP	https://geocoder.melissadata.net/v2/soap/service.svc
SOAP:WSDL	https://geocoder.melissadata.net/v2/soap/service.svc?wsdl
SOAP:Flat WSDL	https://geocoder.melissadata.net/v2/soap/service.wsdl
XML	https://geocoder.melissadata.net/v2/xml/service.svc
REST	https://geocoder.melissadata.net/v2/rest/service.svc

Sample Code #

Adding GeoCoder to a Project #

If you are using the SOAP service with Visual Studio .NET, you need to add a web reference to the service to your project. Click on the Project menu and select Add Web Reference.... Enter the following URL on the Add Web Reference dialog box:

https://GeoCoder.melissadata.net/v2/SOAP/Service.svc

If you are not using Visual Studio .NET, see the documentation for your SOAP interface for the procedure for adding the service to your project.

Submitting an XML Request #

After building your XML string from your data, an XML request to the web service is submitted using an HTTP POST operation to the following URL:

https://GeoCoder.melissadata.net/v2/XML/Service.svc/doGeoCode

Building a REST Request #

Query strings are sent to the web service as part of the URL using an HTTP Get operation appended to following URL:

https://GeoCoder.melissadata.net/v2/REST/Service.svc/doGeoCode

GeoCoder Request #

At the very minimum, a request to the WebSmart GeoCoder consists of the user’s Customer ID and at least one AddressKey.

SOAP Request #

The following Visual Basic Code shows a simple order of operations for building and submitting a RequestArray object, submitting it to the Web Service and retrieving a response object.

Step 1 – Create the Request and Response Objects

Dim ReqGeoCode As New dqwsGeoCode.RequestArray
Dim ResGeoCode As New dqwsGeoCode.ResponseArray

Step 2 – Assign the General Request Values

There are three properties of the Request Array object that apply to the request as a whole. CustomerID is required.

ReqGeoCode.CustomerID = strCustID
ReqGeoCode.TransmissionReference = strTranRef

The Transmission Reference is a unique string value that identifies this request array.

Step 3 – Dimension the Record Array

The maximum number of records per request is 100, therefore the largest dimension will be 99.

ReDim ReqGeoCode.Record(99)

For maximum efficiency, you should dimension the array using the exact number of records being submitted minus one.

Step 4 – Build the Record Array

The exact method for building the array will depend on the exact database software in use, but you will need to loop through every record to be submitted and assign the required values to the corresponding elements for each record in the RequestArray.

ReqGeoCode.Record(intRecord) = New dqwsGeoCode.RequestArrayRecord
ReqGeoCode.Record(intRecord).AddressKey = "92688211282"
ReqGeoCode.Record(intRecord).RecordID = 1

The lines above show only the elements that are absolutely required to submit a record to the web service.

Repeat for each record being submitted with the current RequestArray.

Step 5 – Submit the Request Array

The final step is to create the Service Client Object and then submit the RequestArray object doGeoCode method. This sends the data to the web service and retrieves the ResponseArray object.

GeoCodeClient = New dqwsGeoCode.Service
ResGeoCode = GeoCodeClient.doGeoCode(ReqGeoCode)
GeoCodeClient.Dispose()

XML Request #

The raw XML request is built using whatever XML tools are available via your development tools and submitted to the following URL using an HTTP POST request.

https://GeoCoder.melissadata.net/v2/XML/Service.svc/doGeoCode

Rather than an array of Record objects, an XML request contains a <Record> element for each address record, up to 100.

The following XML Code contains the same request as the SOAP example above.

<?xml version="1.0" ?>
<RequestArray xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <TransmissionReference xmlns="urn:mdWebServiceGeoCode">Test</TransmissionReference>
  <CustomerID xmlns="urn:mdWebServiceGeoCode">XXXXXXXX</CustomerID>
  <Record xmlns="urn:mdWebServiceGeoCode">
    <AddressKey>92688211282</AddressKey>
  </Record>
</RequestArray>

REST Request #

A REST request can submit a single address record via an HTTP GET. The following example uses the same address as the SOAP and XML samples.

https://GeoCoder.melissadata.net/v2/REST/Service.svc/doGeoCode?id=12345678&t=RestTest&key=92688211282

The record ID element does not exist for the REST interface, since you can only submit a single record per request.

Request Elements #

The following section lists the elements that set the basic options for each and identify the user to the Web Service.

Customer ID #

This is a required string value containing the identifier number issued to the customer when signing up for Melissa Data WebSmart Services.

You need a customer ID to access any Melissa Data Web Service. If this element is not populated, the web service will return an error. To receive a customer ID, call your Melissa Data sale representative.

SOAP#

Request.CustomerID = string

XML#

<RequestArray>
  <CustomerID>String</CustomerID>
</RequestArray>

REST#

id={CustomerID}

Transmission Reference #

This is an optional string value that may be passed with each Request Array to serve as a unique identifier for this set of records.

This value is returned as sent by the Response Array, allowing you to match the Response to the Request.

SOAP#

Request.TransmissionReference = string

XML#

<RequestArray>
  <TransmissionReference>String</TransmissionReference>
</RequestArray>

REST#

t={transMissionReference}

Record Elements #

For the SOAP and XML web services, the Request Array will contain an element or property called Record. In SOAP this property is an array of object variables of the type Record. XML will have as many Record elements as there are addresses being submitted to the web service.

The REST interface only allows a single record per request.

Record ID #

This element is a string value containing a unique identifier for the current record.

Use this element to match the record with the record returned with the Response Array.

When using the SOAP interface, if this element is not populated, the web service will automatically insert a sequential number for each record.

There is no equivalent for Record ID for the REST interface.

SOAP#

Request.Record().RecordID = string

XML#

<RequestArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</RequestArray>

AddressKey #

This element is a required eleven-character string value containing a unique number representing a specific location or a six-character Canadian postal code.

This value can beobtained by submitting an address record to the Address Verifier service.

For Canadian GeoCoding, submit the Postal Code instead of an address key.

SOAP#

Request.Record().AddressKey = string

XML#

<RequestArray>
  <Record>
    <AddressKey>String</AddressKey>
  </Record>
</RequestArray>

REST#

key={AddressKey}

GeoCoder Response #

The SOAP interface for the GeoCoder service returns a ResponseArray Object. The primary component of this object is an array of Record objects, one for each record submitted with the RequestArray, containing the verified and standardized address data.

The XML interface returns an XML document containing a number of <Record> elements, one for each record submitted with the Request, containing the verified and standardized address data.

The REST interface returns an XML document with a single <Record> element.

TransmissionReference #

Returns a string value containing the contents of the TransmissionReference element from the original Request.

If you passed any value to the TransmissionReference element when building your request, it is returned here. You can use this property to match the response to the request.

SOAP#

string = Response.TransmissionReference

XML#

<ResponseArray>
  <TransmissionReference>String</TransmissionReference>
</ResponseArray>

Total Records #

Returns a string value containing the number records returned with the current response.

This property returns the number of records processed and returned by the response as a string value.

SOAP#

string = Response.TotalRecords

XML#

<ResponseArray>
  <TotalRecords>String</TotalRecords>
</ResponseArray>

Results #

Returns a string value containing the general and system error messages from the most recent request sent to the service.

Do not confuse this element with the Results element returned with each record. This element returns error messages caused by the most recent request as a whole.

For a list of these codes, see GeoCoder - Service Level Result Codes.

SOAP#

string = Response.Results

XML#

<ResponseArray>
  <Results>String</Results>
</ResponseArray>

Version #

Returns a string value containing the current version number of the GeoCoder web service.

SOAP#

string = Response.Version

XML#

<ResponseArray>
  <Version>String</Version>
</ResponseArray>

Record Elements #

The SOAP version of the Response Array returns a property called Record which is an array of Record objects, one for each record submitted with the original Request Array.

The XML service returns one <Record> element for every record submitted with the original request.

The REST response is identical to the XML response, but will only contain a single <Record> element.

The following section describes the elements returned by each record in the Response Array.

Record ID #

For each record in the Response Array, this element returns a string value containing the unique identifier for the current record if one was passed to the Request Array.

Use this element to match the record in the Response Array with the record originally passed with the request.

SOAP#

string = Response.Record().RecordID

XML#

<ResponseArray>
  <Record>
    <RecordID>String</RecordID>
  </Record>
</ResponseArray>

Results #

For each record in the Response Array, returns a string value containing status and error codes for the current record. Multiple codes are separated by commas.

This element returns the status and error messages for each record in the Response Array.

The Result element may return one or more four-character strings, separated by commas, depending on the result generated by the current record.

If the address in the current record was verified, this element will contain the value GS01 at the very minimum and may include more of the GS codes. If the address could not be verified, the codes beginning with GE will indicate the reason or reasons why verification failed.

For a list of these codes, see GeoCoder - Record Level Result Codes.

SOAP#

string = Response.Record().Results

XML#

<ResponseArray>
  <Record>
    <Results>String</Results>
  </Record>
</ResponseArray>

County #

For each record in the Response Array, these elements return the county name and FIPS Code for the address key submitted for the current record.

The Federal Information Processing Standard (FIPS) is a 5-digit code defined by the U.S. Bureau of Census. The first two digits are a state code and the last three indicate the county within the state.

06037 is the County FIPS for Los Angeles, CA. 06 is the state code for California and 037 is the county code for Los Angeles.

SOAP#

string = Response.Record().Address.County.Fips
string = Response.Record().Address.County.Name

XML#

<ResponseArray>
  <Record>
    <Address>
      <County>
        <Fips>String</Fips>
        <Name>String</Name>
      </County>
    </Address>
  </Record>
</ResponseArray>

Latitude #

For each record in the Response Array, this element returns a string value containing the latitude for the centroid of the location described by the submitted address key or postal code.

Latitude is the geographic coordinate of a point measured in degrees north or south of the equator. The web service uses the WGS-84 standard for determining latitude.

Latitude is returned for both the U.S. and Canada.

Since all North American latitude coordinates are north of the equator, this value will always be positive.

SOAP#

string = Response.Record().Address.Latitude

XML#

<ResponseArray>
  <Record>
    <Address>
      <Latitude>String</Latitude>
    </Address>
  </Record>
</ResponseArray>

Longitude #

For each record in the Response Array, this element returns a string value containing the longitude for the centroid of the location described by the submitted address key or postal code.

Longitude is the geographic coordinate of a point measured in degrees east or west of the Greenwich meridian. The web service uses the WGS-84 standard for determining longitude.

Longitude is returned for both the U.S. and Canada.

Since all North American longitude coordinates are west of the Greenwich meridian, this value will always be negative.

SOAP#

string = Response.Record().Address.Longitude

XML#

<ResponseArray>
  <Record>
    <Address>
      <Longitude>String</Longitude>
    </Address>
  </Record>
</ResponseArray>

Place #

For each record in the Response Array, these elements return the Census Bureau’s Place Code and Place Name for the address key submitted with the current record.

ZIP Code boundaries sometime overlap with city limits and unincorporated areas. The ZIP Code may place a location within one city even though it is physically located within a neighboring area. These properties returns the Census Bureau’s official name for the area containing the location described the submitted address key.

For example, the 92688 ZIP Code is located mostly within the city of Rancho Santa Margarita. However, it also contains parts of the unincorporated area of Los Flores. For these ZIP + 4 codes, the City property of the Address Verifier service would return Rancho Santa Margarita, but the Name property will return Los Flores.

SOAP#

string = Response.Record().Address.Place.Code
string = Response.Record().Address.Place.Name

XML#

<ResponseArray>
  <Record>
    <Address>
      <Place>
        <Code>String</Code>
        <Name>String</Name>
      </Place>
    </Address>
  </Record>
</ResponseArray>

Time Zone #

For each record in the Response Array, these elements return the numeric code and descriptive name for the time zone containing the location described by the submitted address key or postal code.

For a list of these codes, see GeoCoder - Record Level Result Codes.

SOAP#

string = Response.Record().Address.TimeZone.Code
string = Response.Record().Address.TimeZone.Name

XML#

<ResponseArray>
  <Record>
    <Address>
      <TimeZone>
        <Code>String</Code>
        <Name>String</Name>
      </TimeZone>
    </Address>
  </Record>
</ResponseArray>

Core Based Statistical Area #

For each record in the Response Array, these six elements return the U.S. Census Bureau’s Core Based Statistical Area (CBSA) data for the location associated with the submitted address key.

Metropolitan and micropolitan statistical areas (metro and micro areas) are geographic entities defined by the U.S. Office of Management and Budget (OMB) for use by Federal statistical agencies in collecting, tabulating, and publishing Federal statistics. The term “Core Based Statistical Area” (CBSA) is a collective term for both metro and micro areas. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. Each metro or micro area consists of one or more counties and includes the counties containing the core urban area, as well as any adjacent counties that have a high degree of social and economic integration (as measured by commuting to work) with the urban core.

The CBSA Code is a five-digit code for the specific CBSA associated with the location described by the submitted address key. The Level states whether the particular CBSA is a metropolitan or micropolitan area. The Title returns the official U.S. Census Bureau name for the CBSA.

Some CBSA’s are broken into parts known as divisions. In this case, the CBSA Division elements will also be populated. If not, these elements will be empty. Each division also has a Code, Level and Title.

SOAP#

string = Response.Record().Address.CBSA.Code
string = Response.Record().Address.CBSA.Level
string = Response.Record().Address.CBSA.Title
string = Response.Record().Address.CBSA.CBSADivisionCode
string = Response.Record().Address.CBSA.CBSADivisionLevel
string = Response.Record().Address.CBSA.CBSADivisionTitle

XML#

<ResponseArray>
  <Record>
    <Address>
      <CBSA>
        <Code>String</Code>
        <Level>String</Level>
        <Title>String</Title>
        <CBSADivisionCode>String</CBSADivisionCode>
        <CBSADivisionLevel>String</CBSADivisionLevel>
        <CBSADivisionTitle>String</CBSADivisionTitle>
      </CBSA>
    </Address>
  </Record>
</ResponseArray>

Census Block #

For each record in the Response Array, this element returns the Census Block number associated with the location described by the submitted address key.

Census blocks, the smallest geographic area for which the Bureau of the Census collects and tabulates decennial census data, are formed by streets, roads, railroads, streams and other bodies of water, other visible physical and cultural features, and the legal boundaries shown on Census Bureau maps.

The Census Block is a four-character string value. The first digit is the Block Group and the last three characters (if any) are the Block Number. The block group returns a one-character string containing the block group number.

SOAP#

string = Response.Record().Address.Census.Block

XML#

<ResponseArray>
  <Record>
    <Address>
      <Census>
        <Block>String</Block>
      </Census>
    </Address>
  </Record>
</ResponseArray>

Census Tract #

For each record in the Response Array, this element returns the Census Tract number associated with the location described by the submitted address key.

Census Tracts are small, relatively permanent statistical subdivisions of a county. Census Tracts are delineated for all metropolitan areas (MA’s) and other densely populated counties by local census statistical areas committees following Census Bureau guidelines (more than 3,000 Census Tracts have been established in 221 counties outside MA’s).

The CensusTract property is usually returned as a 4-digit string. However, in areas that experience substantial growth, a Census Tract may be split to keep the population level even. When this happens, a 6-digit number will be returned.

The web service requires a full nine-digit ZIP with a valid Plus 4 add-on to return the Census Tract. If a five-digit ZIP is submitted, the Census Tract will not be returned.

SOAP#

string = Response.Record().Address.Census.Tract

XML#

<ResponseArray>
  <Record>
    <Address>
      <Census>
        <Tract>String</Tract>
      </Census>
    </Address>
  </Record>
</ResponseArray>

Response Object XML Format #

The following shows the structure of the XML document returned by the GeoCoder Service.

<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Version xmlns="urn:mdWebServiceGeoCode">2.0.51</Version>
<TransmissionReference xmlns="urn:mdWebServiceGeoCode">Test
</TransmissionReference>
<Results xmlns="urn:mdWebServiceGeoCode" />
<TotalRecords xmlns="urn:mdWebServiceGeoCode">1</TotalRecords>
  <Record xmlns="urn:mdWebServiceGeoCode">
    <RecordID>1</RecordID>
    <Results>GS05</Results>
    <Address>
      <County>
        <Name>Orange</Name>
        <Fips>06059</Fips>
      </County>
      <Latitude>33.637550</Latitude>
      <Longitude>-117.606840</Longitude>
      <Place>
        <Code>0659587</Code>
        <Name>Rancho Santa Margarita</Name>
      </Place>
      <TimeZone>
        <Name>Pacific Time</Name>
        <Code>08</Code>
      </TimeZone>
      <CBSA>
        <Code>31100</Code>
        <Title>Los Angeles-Long Beach-Santa Ana, CA</Title>
        <Level>Metropolitan Statistical Area</Level>
        <CBSADivisionCode>42044</CBSADivisionCode>
        <CBSADivisionTitle>Santa Ana-Anaheim-Irvine, CA</CBSADivisionTitle>
        <CBSADivisionLevel>Metropolitan Statistical Area</CBSADivisionLevel>
      </CBSA>
      <Census>
        <Block>1005</Block>
        <Tract>032053</Tract>
      </Census>
    </Address>
  </Record>
</ResponseArray>

Reference Guide

Contents

Reference Guide#

SOAP#

XML#

REST#

SOAP#

XML#

REST#

SOAP#

XML#

SOAP#

XML#

REST#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#

SOAP#

XML#