Reference Guide#

Introduction#

International address data quality is a challenge for organizations of all sizes. International data with its differing address structures, terms, and alphabets can if handled poorly have a substantial negative impact on your data-driven initiatives. Melissa Data® provides customizable developer tools have been designed to help efficiently manage and improve the data quality levels in your global contact data, all while providing for superior performance and profitability at a favorable price point. Global Address Object can be used as a turning point at which the international data collected across your organization can be transformed into usable reliable information and maintained that way. By using Global Address Object, you’ll reduce costly international undeliverable and return mail, increase effective multinational communication efforts, and save money on all the data driven initiatives across the organization.

Setup and List of Files#

To see how to set up the Global Address Object, the list of files that will be downloaded and used, and the system requirements to run the Object, please visit the GitHub Sample Code.

Address Handling#

A key concept critical to the use of the Global Address Object is to understand how the object handles address data as inputs and outputs. Global Address Object can accept all address data for input through a set/get paradigm.

Input Methods#

For input address data there are two functions: SetInputParameter and GetInputParameterNames.

SetInputParameter#

This function takes a name/value parameter to set input address data for processing within the Global Address Object.

GetInputParameterNames#

This function returns an array/list of all named parameters available as input in the Global Address Object.

Output Methods#

For returning address quality metrics and results there is a single output function, GetOutputParameter, and a corresponding function, GetOutputParameterNames.

GetOutputParameterNames#

This function provides an array/list of the parameter names available for output after verifyAddress has been called for processing.

GetOutputParameter#

This function takes a named parameter to request the return of output address data after input address data has been processed by verifyAddress.

Interface Use#

Creating an Instance#

  1. Create an instance of the Global Address Object’s GlobalAddr Interface.

    Set addPtr = new instance of GlobalAddr
    

    The first set of steps is to initialize the instance of the GlobalAddr Interface.

  2. If necessary, call SetLicenseString and pass the License Key as mentioned in Licensing. Again, this is not necessary if the License Key is provided as the recommended environment variable.

  3. Call the SetPathToGlobalAddrFiles function with file a path as a parameter pointing to the location of the Global Address Object reference data files.

  4. Call the InitializeDataFiles function. If it returns anything other than 0, then initialization has failed. Check the return value of the GetInitializeErrorString function to find out why this happened.

    CALL InitializeDataFiles RETURNING result
    
    If result <> 0 THEN
        Call GetInitializeErrorString RETURN ErrorMessage
        Display ErrorMessage
    Else
        Process Addresses
    End If
    
  5. At this point, we are ready to load the GlobalAddr with address input data for verification correction etc.

Setting Parameters for Input#

Setting input address data is the first step in global address validation. Before any verification or correction can be completed, the originating input address data must be set into the Global Address Object’s input parameters. Parameters are set into the Global Address Object as name/value pairs. The complete list of name/value pairs for input and output can be found in Input Parameters and Output Parameters.

So, using our Global Address Object addPtr defined previously, we will set the following sample address into the input parameters:

Sample Address

Carretera Rioseco 2

34170 Villamartín De Campos Palencia

SPAIN

Result =  addPtr.SetInputParameter(“inputCountry”, “Spain”)
Result =  addPtr.SetInputParameter(“inputAddressLine1”, “Carretera Rioseco 2”)
Result =  addPtr.SetInputParameter(“inputAddressLine2”, “34170 Villamartín De Campos Palencia”)

Notice that the input in this case is in an address line format. Global Address Object will attempt to field and parse these address lines before processing the verification and correction of the address data.

Setting the outputPreference parameter tells the Global Address Object to return the results based on the language/alphabet parameter specified. This is accomplished via either translation, transliteration, or a combination of both.

Once we have our parameters set, we are ready to make the processing call to do some work on the input address data.

Functions for Processing Input#

There are 3 functions that process data provided to the Global Address Object, but only VerifyAddress utilizes the input parameters set in Setting Parameters for Input. TranslateText and TransliterateText are utilized to map or move any input value and language combination to another output value and language combination.

VerifyAddress

The VerifyAddress function takes in no parameters, but reads from the values set in the SetInputParameter call(s) to attempt to process the input data for fielding, parsing, verification/correction and return formatting. The results from calling VerifyAddress are accessible by utilizing the functions defined in Getting Results and Output.

The call is very straightforward, but again, dependent on input parameters being defined.

Intval = VerifyAddress()

The return integer intval from this call has no determination or value related to the results of the call. The return only defined a 0 or 1 for the success or failure of the function call itself. Getting to the results of the VerifyAddress call itself, is the job of GetOutputParameter and GetOutputParameterNames.

Getting Results and Output#

There are three functions available for getting return values and results from the Global Address Object: GetInputParameterNames, GetOutputParameterNames and GetOutputParameter.

GetInputParameterNames#

GetInputParameterNames returns the application an array/list of input parameter names like the input values referenced in Setting Parameters for Input.

GetOutputParameterNames#

GetOutputParameterNames functions in the same manner as GetInputParameterNames, but is specifically for getting outputted results from the address verification/correction process initialized with verifyAddress.

For a complete list of input and output parameter names with definitions, see Parameters.

GetOutputParameter#

The GetOutputParameter function is the counterpart to SetOutputParameter. This function takes in a parameter name, such as administrativeArea and returns the value “Queensland” for an address such as the one below.

Sample Address

91 Queen Street, Brisbane QLD 4000 Australia

In this example, QLD is the administrative area (US terms State/Province) abbreviation for Queensland.

House number = 91
Street = Queen Street
Postal Code = 4000
Administrative Area = QLD
City/Locality = Brisbane
Country Name = Australia

To pass this fielded address data to the object as parameters the following calls would be coded:

Result =  addPtr.SetInputParameter(“inputCountry”, “Australia”)
Result =  addPtr.SetInputParameter(“premiseNumber”, “91”)
Result =  addPtr.SetInputParameter(“PostalCode”, “4000”)
Result =  addPtr.SetInputParameter(“AdministrativeArea”, “QLD”)
Result =  addPtr.SetInputParameter(“Locality”, “Brisbane”)
Result =  addPtr.SetInputParameter(“thoroughfareName”, “Queen Street”)
// Now that all input values are set, call verifyAddress to attempt to process input
Intval = VerifyAddress()
// Now get values if intval is successful
If intval = true
        outputResult1 = addPtr.GetOutputParameter(“administrativeArea”)
        outputResult2 = addPtr.GetOutputParameter(“inputAdministrativeArea”)
End if

The variable outputResult1 contains the resulting administrative area, as already mentioned: Queensland. It important to note that outputResult2 also contains a value which is the original input value of QLD as administrative area.

Methods#

Setup Methods - Set#

InitializeDataFiles#

Syntax:

InitializeDataFiles();

Returns:

Initialization Status

Return Type:

ProgramStatus

This function is used to set the physical path to the Global Address Object’s reference data files.


SetLicenseString#

Syntax:

SetLicenseString(String License);

Returns:

Successful

Return Type:

Boolean

This function is used to set the License Key into the Global Address Object. This can also be accomplished by utilizing an environmental variable.


SetPathToGlobalAddrFiles#

Syntax:

SetPathToGlobalAddrFiles(String FilePath);

Return Type:

Void

This function is used to set the physical path to the Global Address Object’s reference data files.


Setup Methods - Get#

GetBuildNumber#

Syntax:

GetBuildNumber();

Returns:

Build Number

Return Type:

String

This function returns the version number for the Global Address Object


GetDatabaseDate#

Syntax:

GetDatabaseDate();

Returns:

Database Date

Return Type:

String

This function returns the build date for the reference data files utilizes by Global Address Object.


GetDatabaseExpirationDate#

Syntax:

GetDatabaseExpirationDate();

Returns:

Database Expiration Date

Return Type:

String

This function return the expiration date for the reference data files being used by Global Address Object if applicable.


GetInitializeErrorString#

Syntax:

GetInitializeErrorString();

Returns:

Error Description

Return Type:

String

This function will return the error string detail related to a failure or error initializing the reference data file(s) and/or Global Address Object.


GetLicenseExpirationDate#

Syntax:

GetLicenseExpirationDate();

Returns:

License Expiration Date

Return Type:

String

This function returns the expiration date for the License Key set in the environmental variable or by utilizing SetLicenseString.


Input Methods#

SetInputParameter#

Syntax:

SetInputParameter(String InputParameter, String Value);

Returns:

Successful

Return Type:

Boolean

This function allows you to set the input value for a particular address input parameter.

Format

mdGlobalAddr.SetInputParameter(“inputParameter”,”value”)

Example

mdGlobalAddr.SetInputParameter(“AddressLine1”,”123 Main St”)


Processing Methods#

VerifyAddress#

Syntax:

VerifyAddress();

Returns:

Status

Return Type:

Integer

This function is the primary processing function in Global Address Object. It takes the input address data values set as input parameters and attempts to verify and correct the data then return it in the requested language/alphabet.


Output Methods#

GetOutputParameter#

Syntax:

GetOutputParameter(String ParameterName);

Returns:

Parameter

Return Type:

String

This function allows you to get the output value for a particular address output parameter after verification has occurred.

Format

mdGlobalAddr.GetOutputParameter(“outputParameter”)

Example

mdGlobalAddr.GetOutputParameter(“AddressLine1”)


Input Parameters#

Though they are listed in mixed case, the parameters are not case sensitive.

All of the following inputs can be set using SetInputParamter and can also be output using GetOutputParameter.


Processing Configuration Parameters#

countryOfOrigin#

The country of origin (the address being validated is the destination). Used to determine whether the destination country should be added to the formatted address.

Option Name

Parameter

Description

countryOfOrigin

(Any valid ISO-3166-1 Alpha-2, ISO-3166-1 Alpha-3, or ISO-3166-1 Numeric code)

  • If blank, invalid, or the same as the destination country, then the destination country is not appended to the end of the formatted address.

  • If valid and different from the destination country, then the destination country is appended to the formatted address.

  • US or US Territory:

    • If countryOfOrigin and destination country being verified are both US or US Territories then the country will not be appended to formattedAddress.

    • US Territories will have “United States of America” appended if the countryOfOrigin is not a US Territory, but the countryName and ISO codes will be that of the territory.

    • Canada is treated like any other non-US Territory.

outputPreference#

This is the script type used for all applicable fields.

Option Name

Parameter

Description

outputPreference

[Blank]

Default. Returns the same script that is sent in.

LATIN

Returns in the Latin script.

NATIVE

Returns in the native script for the designated country.

inputFormattedAddressSeparator#

This is a string used to delimit line in the formattedAddress output field. This string can be one or multiple characters.

Input Address Parameters#

inputOrganization#

The organization name associated with the address record.

inputAddressLine1#

Required.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine2#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine3#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine4#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine5#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine6#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine7#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputAddressLine8#

Optional.

The input field for the address. This should contain the delivery address information (house number, thoroughfare, building, suite, etc.) but should not contain locality information (locality, administrative area, postal code, etc.) which have their own inputs.

inputDoubleDependentLocality#

Optional.

The smallest population center data element. This depends on the Locality and DependentLocality elements.

inputDependentLocality#

Optional.

The smaller population center data element. This depends on the Locality element.

US Term: Urbanization

In terms of US Addresses, this element applies only to Puerto Rican addresses. It is used to break ties when a ZIP Code™ is linked to multiple instances of the same address.

inputLocality#

Required.

The most common population center data element.

US Term: City

Canada Term: Municipality

inputSubAdministrativeArea#

Optional.

The smallest geographic data element.

US Term: County

inputAdministrativeArea#

Required.

The most common geographic data element.

US Term: State

Canada Term: Province

inputSubNationalArea#

Optional.

The administrative region within a country on an arbitrary level below that of the sovereign state.

inputPostalCode#

Required.

The complete postal code for a particular delivery point.

US Term: ZIP

Canadian Term: Postcode

If all three elements are provided and the PostalCode is incorrect, it can be corrected from the data on the Locality and AdministrativeArea.

inputCountry#

Required.

The country name, abbreviation, or code.

Output Parameters#

Though they are listed in mixed case, the parameters are not case sensitive.

All of the following outputs can be returned using GetOutputParameter.


Output Detail Parameters#

buildNumber#

Build number of the Global Address Object API.

databaseDate#

Release date of the database.

databaseExpirationDate#

Expiration date of the database.

dst#

A true/false value delineating if the given address is in a time zone that supports Daylight Savings Time (DST).

initializeErrorString#

An error string detailing any failure or error in initializing the reference data file(s) and/or Global Address Object.

licenseStringExpirationDate#

Expiration date for the License Key set with SetLicenseString.

remnants#

Any elements parsed from the input address data which could not be processed or were not relevant to the address processing are returned in the remnant parameter.

resultCodes#

Result code(s) generated for the address.

Reference Global Address Object Result Codes for more information.

timezone#

Name of the timezone of the address.

utc#

Coordinated Universal Time (Universal Time Coordinated). Code that designates the UTC offset for the given time zone of the address. This does not indicate differences due to daylight savings time.

Output Address Parameters#

organization#

This is a string value that matches the Organization request element. It is not modified or populated by the service.

US Term: Business or Company

addressLine1#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine2#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine3#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine4#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine5#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine6#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine7#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

addressLine8#

These are the string values that will return the standardized or corrected contents of the input address. These lines will include the entire address including the locality, administrative area, and postal code.

deliveryLine#

The delivery portion of the full address, from the sub-premise and house number to the street information. This does not include area information like doubledependent locality, dependent locality, locality, administrative area, and postal code if those values are available for the country.

localityLine#

The locality information of the full address. This includes information such as doubledependent locality, dependent locality, locality, administrative area, and postal code if those values are available for the country. This does not include sub-premise and house number to the thoroughfare information.

formattedAddress#

Mailing address. The full mailing address in the preferred format for the country of the address. This includes the Organization as the first line, one or more lines in the origin country’s format, and the destination country (if required). Separate lines will be delimited by what is specified in the option.

DeliveryPointSuffix#

This is a country dependent field. This field returns an identifier that represents a suffix code usually tied to a delivery point.

US

This returns the 2 digit delivery point assigned by the USPS to an DPV validated address.

GB

This is a 2 character (first is numerical, 2nd character is alphabetic) that is assigned by Royal Mail. When added to the postal code, this allows each live delivery point to be uniquely identified.

AddressTypeCode#

This is a country dependent field. This field returns a code to identify the type of address that the input is identified as.

US

Code

Description

A

Alias

F

Firm or Company

G

General Delivery

H

Highrise or Business Complex

P

PO Box

R

Rural Route

S

Street or Residential

CA

Code

Description

1

Street

2

Street Served by Route and GD

3

Lock Box

4

Route Service

5

General Delivery

B

LVR Street

C

Government Street

D

LVR Lock Box

E

Government Lock Box

L

LVR General Delivery

K

Building

GB

Code

Description

L

This address is identified as having a large user postal code. This is due to the large volume of mail received at that address, or because a PO Box or Selectapost service has been set up.

S

This address is identified as having a smaller user postal code. This means this postal code will have usually around 15 delivery points but never more than 100.

AddressKey#

This is a country dependent field. This field returns an identifier that is used in the country by the official postal agency or another well-recognized agency or standard.

US

This returns a 11 digit code representing the combination of the zip code, the plus4, and the delivery point. This is a fairly good representation of a unique US address and often used as the core of postal barcode. However, this code is not guaranteed to be unique to an individual address, please use the MelissaAddressKey instead for that purpose. It is possible that this field is empty or not 11 digits if the address is a Non-USPS address.

GB

This field returns the UDPRN, which stands for Unique Delivery Point Reference Number. It is a 8 character code that is assigned and maintained by Royal Mail to each delivery point address.

MelissaAddressKey#

This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address.

With AddressKey (US and Canada only), if an address zip code changes, the AddressKey would also change. Melissa Address Key (MAK) is independent and will not change. This makes MAK a good way to permanently identify and locate addresses. Once you have a MAK it can be used as an input in most Melissa services and thus is a good tool for deduping.

Currently available for US, AT, AU, BE, BM, BR, CA, CH, DE, DK, ES, FR, GB, IE, IS, IT, KR, LT, MC, NC, NL, NO, PT, SG, SI, and TR with many more countries planned for the future.

MelissaAddressKeyBase#

Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building. This field also returns a 10-digit proprietary key. Note, if we can validate the address to the building but not the suite, we can return just the BaseMAK.

Parsed Sub-Premises Parameters#

building#

Descriptive name identifying an individual location. This is a string value that is the parsed Building element from the output.

subBuilding#

Descriptive name identifying an individual location. More specific than building. This is a string value that is the parsed premisesType parameter from the output.

subBuildingNumber#

Sub building number indicator within building field. Parsed from the subBuilding parameter.

subBuildingType#

Sub building type indicator within building field. Parsed from the subBuilding parameter.

subPremises#

Alphanumeric code identifying an individual location. More specific than premises.

US Term: Suite

subPremisesNumber#

Sub premises number indicator within premises field. Parsed from the subPremises parameter.

US Term: Suite Number

subPremisesType#

Sub premises type indicator within premises field. Parsed from the subPremises parameter.

US Term: Suite Name

subPremisesLevel#

Alphanumeric code identifying an individual location. More specific than sub premises.

subPremisesLevelNumber#

Sub premises level number indicator within premises field. Parsed from the subPremisesLevel parameter.

subPremisesLevelType#

Sub premises level type indicator within premises field. Parsed from the subPremisesLevel parameter.

Parsed Thoroughfare Parameters#

premises#

US Term: Street Number

premisesNumber#

Alphanumeric indicator within premises field. Parsed from the premises parameter.

US Term: House Number

premisesType#

Leading premise type indicator within premises field. Parsed from the premises parameter.

thoroughfare#

This value is a part of the address lines and contains all the sub-elements of the thoroughfare like trailing type, thoroughfare name, pre direction, post direction, etc.

US Term: Street

thoroughfareLeadingType#

Leading thoroughfare type indicator parsed from the thoroughfare parameter. A leading type is a thoroughfare type that is placed before the thoroughfare. This value is a part of the Thoroughfare field. For example, the thoroughfare type of “Rue” in Canada and France is placed before the thoroughfare, making it a leading type.

US Term: Not used in the US

thoroughfareName#

Name indicator parsed from the thoroughfare parameter.

US Term: Street Name

thoroughfarePostDirection#

Postfix directional parsed from the thoroughfare parameter.

US Term: Post Direction

thoroughfarePreDirection#

Prefix directional parsed from the thoroughfare parameter.

US Term: Pre Direction

thoroughfareTrailingType#

Trailing thoroughfare type indicator parsed from the thoroughfare parameter. A trailing type is a thoroughfare type that is placed after the thoroughfare. This value is a part of the Thoroughfare field. For example, the thoroughfare type of “Avenue” in the US is placed after the thoroughfare, making it a trailing type.

US Term: Street Suffix

thoroughfareTypeAttached#

Thoroughfare type connected to the thoroughfare name without a space. This is common in Germany. For example, “Berlinerstr.” “str.” stands for strasse and is the thoroughfare type attached, while “Berliner” is the thoroughfare name.

Parsed Dependent Thoroughfare Columns#

dependentThoroughfare#

Block data element or dependent street. This is used when there are more than one thoroughfares with the same name in one locality. An adjoining thoroughfare is used to uniquely identify the target thoroughfare. This is rarely used.

US Term: Dependent Street

dependentThoroughfareLeadingType#

Thoroughfare type at the beginning of the dependent thoroughfare. The leading type is parsed from the dependentThoroughfare parameter. For example, if the dependent thoroughfare is “St. Hickory E,” the dependent thoroughfare leading type would be “St.”

dependentThoroughfareName#

Dependent thoroughfare name parsed from the dependentThoroughfare parameter. For example, if the dependent thoroughfare is “E Hickory Ln,” the dependent thoroughfare name would be “Hickory.”

dependentThoroughfarePostDirection#

Cardinal directional at the end of the dependent thoroughfare. The postfix directional is parsed from the dependentThoroughfare parameter. For example, if the dependent thoroughfare is “Hickory Ln N,” the dependent thoroughfare post direction would be “N.”

dependentThoroughfarePreDirection#

Cardinal directional at the beginning of the dependent thoroughfare. The prefix directional is parsed from the dependentThoroughfare parameter. For example, if the dependent thoroughfare is “W Hickory Ln,” the dependent thoroughfare pre direction would be “W.”

dependentThoroughfareTrailingType#

Thoroughfare type at the end of the dependent thoroughfare. The trailing type is parsed from the dependentThoroughfare parameter. For example, if the dependent thoroughfare is “W Hickory Ln,” the dependent thoroughfare trailing type would be “Ln.”

dependentThoroughfareTypeAttached#

Dependent thoroughfare type connected to the dependent thoroughfare name without a space. This is common in Germany. For example, “Berlinerstr.” “str.” stands for strasse and is the dependent thoroughfare type attached, while “Berliner” is the dependent thoroughfare name.

Parsed Postal Facility Columns#

postBox#

Post box information for a particular delivery point.

postalCode#

Complete postal code for a particular delivery point. In U.S. plus 4 is not required but will be appended if address is verified. Most countries have some form of a postal code system.

US Term: Zip Code

postOfficeLocation#

Parsed Regional Columns#

administrativeArea#

This is a common geographic area unit for larger countries. Often referred to as State or Province.

US Term: State

countyName#

US Only. Sub Administrative Area. Smallest geographic data element.

dependentLocality#

A dependent locality is a logical area unit that is smaller than a locality but larger than a double dependent locality or thoroughfare. It can often be associated with a neighborhood or sector. Great Britain is an example of a country that uses double dependent locality. In the United States, this would correspond to Urbanization, which is used only in Puerto Rico.

US Term: Urbanization

doubleDependentLocality#

A double dependent locality is a logical area unit that is smaller than a dependent locality but bigger than a thoroughfare. This field is very rarely used. Great Britain is an example of a country that uses double dependent locality.

locality#

This is the most common geographic area and used by virtually all countries. This is usually the value that is written on a mailing label and referred to by terms like City, Town, Postal Town, etc.

US Term: City

subAdministrativeArea#

This is a logical area that that is smaller than the administrative area but larger than a locality. While many countries can have a sub-administrative area value, it is very rarely used as part of an official address.

US Term: County

subNationalArea#

A sub-national area is a logical area unit that is larger than an administrative area but smaller than the country itself. It is extremely rarely used.

Extra Output Address Parameters#

latitude#

North-south geographic coordinate for a particular delivery point.

longitude#

East-west geographic coordinate for a particular delivery point.

Extra Output Country Parameters#

countryName#

Full country name. Can be a nickname.

iso2Code#

ISO 3166 2-character country code.

For example:

Country

Code

United States

US

Canada

CA

Philippines

PH

iso3Code#

ISO 3166 3-character country code.

For example: ============== ========== Country Code ============== ========== United States USA Canada CAN Philippines PHL ============== ==========

isoCountryNumber#

ISO 3166 3-digit numeric country code.

For example:

Country

Code

United States

840

Canada

124

Philippines

608

CountrySubdivisionCode#

This field returns the ISO 3166-2 country sub-division code. This code is part of the ISO 3166 international standard to represent the relevant administrative divisions and dependent territories for a country. For most countries, this code is tied to the administrative area. Not all countries currently return this code but we are planning on adding more.

formalCountryName#

Official Name for the country.

US Only Output Parameters#

USCityAbbreviation#

Get the abbreviated city name.

USPlus4#

Get the plus4 by itself.

USCarrierRoute#

Get the Carrier Route.

USDeliveryPointCode#

Get the 2 digit delivery point code

USDeliveryPointCheckDigit#

Get the 1 digit devliery point check digit

USCongressionalDistrict#

Get the congressional district number of the address

DeliveryIndicator#

This field returns a one character code that indicates if the address is a residence (R), business (B), or unknown (U). It is not available for all countries. Currently, it is available only for the US but more countries are planned for future inclusion.

USCensusTract#

Census Tract value

USCensusBlock#

Census Block value

USBlockSuffix#

Census Block Suffix

USCountyFips#

County FIPS number

USCountyName#

County Name

USPlaceCode#

Census Place Code

USPlaceName#

Census Place Name

USCBSACode#

Census CBSA Code

USCBSATitle#

Census CBSA Title

USCBSALevel#

Census CBSA Level

USCBSADivisionCode#

Census CBSA Division Code

USCBSADivisionTitle#

Census CBSA Division Title

USCBSADivisionLevel#

Census CBSA Division Level

USCensusKey#

Census Key value

USCountySubdivisionCode#

Census County Subdivision Code

USCountySubdivisionName#

Census County Subdivision Name

USElementarySchoolDistrictCode#

Elementary School District Code

USElementarySchoolDistrictName#

Elementary School District Name

USSecondarySchoolDistrictCode#

Secondary School District Code

USSecondarySchoolDistrictName#

Secondary School District Name

USUnifiedSchoolDistrictCode#

Secondary School District Code

USUnifiedSchoolDistrictName#

Secondary School District Name

USStateDistrictLower#

State Lower Congressional District Number

USStateDistrictUpper#

State Upper Congressional District Number

USZipType#

Returns the Zip Type for US

Code

Description

A blank zip type is a regular zip

P

Zip code specifically for PO Boxes

U

Unique Zip Code

M

Military Zip Code

Result Codes#

For details of all result codes please visit here

AS - Address Status#

Code

Short Description

Long Description

AS09

Foreign Address

The address is in a non-supported country.

AE - Address Error#

Code

Short Description

Long Description

AE01

General Error

The address could not be verified. This is likely due to a missing or invalid locality or postal code.

AE02

Unknown Street

Could not match the input street to a unique street name. Either no matches or too many matches found.

AE03

Component Mismatch Error

The combination of directionals (N, E, SW, etc) and the suffix (AVE, ST, BLVD) is not correct and produced multiple possible matches.

AE05

Multiple Match

The address was matched to multiple records. There is not enough information available in the address to break the tie between multiple records.

AE06

Early Warning System

US Only. This address currently cannot be verified but was identified by the Early Warning System (EWS) as belonging to a upcoming area and will likely be included in a future update.

AE07

Missing Minimum Address

Minimum requirements for the address to be verified is not met. Address must have at least one address line and also the postal code or the locality/administrative area.

AE08

Sub Premise Number Invalid

The thoroughfare (street address) was found but the sub premise (suite) was not valid.

AE09

Sub Premise Number Missing

The thoroughfare (street address) was found but the sub premise (suite) was missing.

AE10

Premise Number Invalid

The premise (house or building) number for the address is not valid.

AE11

Premise Number Missing

The premise (house or building) number for the address is missing.

AE12

Box Number Invalid

The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is invalid.

AE13

Box Number Missing

The PO (Post Office Box), RR (Rural Route), or HC (Highway Contract) Box number is missing.

AE14

PMB Number Missing

US Only. The address is a Commercial Mail Receiving Agency (CMRA) and the Private Mail Box (PMB or #) number is missing.

AE17

Sub Premise Not Required (Deprecated - See AS23)

A sub premise (suite) number was entered but the address does not have secondaries. (Deprecated - See AS23)

AC - Address Change#

Code

Short Description

Long Description

AC01

Postal Code Change

The postal code was changed or added.

AC02

Administrative Area Change

The administrative area (state, province) was added or changed.

AC03

Locality Change

The locality (city, municipality) name was added or changed.

AC09

Dependent Locality Change

The dependent locality (urbanization) was changed.

AC10

Thoroughfare Name Change

The thoroughfare (street) name was added or changed due to a spelling correction.

AC11

Thoroughfare Type Change

The thoroughfare (street) leading or trailing type was added or changed, such as from “St” to “Rd.”

AC12

Thoroughfare Directional Change

The thoroughfare (street) pre-directional or post-directional was added or changed, such as from “N” to “NW.”

AC13

Sub Premise Type Change

The sub premise (suite) type was added or changed, such as from “STE” to “APT.”

AC14

Sub Premise Number Change

The sub premise (suite) unit number was added or changed.

AC15

Double Dependent Locality Change

The double dependent locality was added or changed.

AC16

SubAdministrative Area Change

The subadministrative area was added or changed.

AC17

SubNational Area Change

The subnational area was added or changed.

AC18

PO Box Change

The PO Box was added or changed.

AC19

Premise Type Change

The premise type was added or changed.

AC22

Organization Change

The organization was added or changed.

GS - Geocode Status#

Code

Short Description

Long Description

GS01

Geocoded to Street Level

The record was coded to the street level (Zip+4 for US, full postal code for CA).

GS02

Geocoded to the Neighborhood Level

The record was geocoded down to neighborhood level (Zip+2 for US).

GS03

Geocoded to Community Level

The record was coded to the community level (ZIP centroid for US, 3-digit postal code for CA).

GS05

Geocoded to Rooftop Level

The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center.

GS06

Geocoded to Interpolated Rooftop Level

The record was geocoded down to the rooftop level using interpolation (educated estimations using street coordinates). The point may be in or close to the property boundaries.

GE - Geocode Error#

Code

Short Description

Long Description

GE01

Regional Geocode Not Found

Geocode could not be appended for the input locality or postal code.

GE02

No Geocode for Input Address

The input address did not provide enough valid information to append a geocode.

GE03

Demo Mode

Geocoder is in Demo mode and a zip code outside the Demo range was detected.

GE04

Data Files Expired

Geocoder data files are expired. Please update with the latest data files.

AV - Address Verification#

Code

Short Description

Long Description

AV11

Administrative Area Partial

The address has been partially verified to the Administrative Area (State) Level, which is NOT the highest level possible with the reference data.

AV12

Locality Partial

The address has been partially verified to the Locality (City) Level, which is NOT the highest level possible with the reference data.

AV13

Thoroughfare Partial

The address has been partially verified to the Thoroughfare (Street) Level, which is NOT the highest level possible with the reference data.

AV14

Premise Partial

The address has been partially verified to the Premise (House or Building) Level, which is NOT the highest level possible with the reference data.

AV21

Administrative Area Full

The address has been verified to the Administrative Area (State) Level, which is the highest level possible with the reference data.

AV22

Locality Full

The address has been verified to the Locality (City) Level, which is the highest level possible with the reference data.

AV23

Thoroughfare Full

The address has been verified to the Thoroughfare (Street) Level, which is the highest level possible with the reference data.

AV24

Premises Full

The address has been verified to the Premise (House or Building) Level, which is the highest level possible with the reference data.

AV25

SubPremises Full

The address has been verified to the SubPremise (Suite) or PO Box Level, which is the highest level possible with the reference data.

Address Type US#

Code

Description

A

Alias

F

Firm or Company

G

General Delivery

H

Highrise or Business Complex

P

PO Box

R

Rural Route

S

Street or Residential

Address Type Canada#

Code

Description

1

Street

2

Street Served by Route and GD

3

Lock Box

4

Route Service

5

General Delivery

B

LVR Street

C

Government Street

D

LVR Lock Box

E

Government Lock Box

L

LVR General Delivery

K

Building