Get Candidate Addresses - Spectrum_OnDemand - addressing - web_services

Get Candidate Addresses returns a list of addresses that are considered matches for a given input address. Get Candidate Addresses returns candidate addresses only if the input address matches multiple addresses in the postal database. If the input address matches only one address in the postal database, then no address data is returned.

For addresses outside the U.S. and Canada, you may notice inconsistent results between the multiple matches returned by Validate Address and the results for that same address returned by Get Candidate Addresses. If you experience inconsistent results, it is likely because you set the performance tuning setting in Validate Address to a value other than 100. To obtain consistent results between Get Candidate Addresses and Validate Address, set the performance tuning option to 100.

Note: By default, Get Candidate Addresses does not match to individual house numbers. Rather, it uses house number ranges for each street. After Get Candidate Addresses has determined the street name, city name, state/province name, and postal code, it checks to make sure the input house number falls within one of the ranges of house numbers given for the matched street name. The same type of logic applies to unit numbers. If you want to determine that an individual house number is valid, you should use the Validate Address Delivery Point Validation (DPV) processing option. DPV processing is only available for U.S. addresses.

The Canadian coder contains a reverse lookup routine that takes as input a specific postal code and returns the street information stored in the database for that postal code. To use this function enter nothing but a Canadian postal code in the PostalCode field. See the second example to view the return from a sample postal code.

Get Candidate Addresses is part of Spectrum Universal Address.

U.S. Address Example

AddressLine1:

PO Box 1 City: NY State: NY

Preview Output:

Field Name	Output Record 1	Output Record 2
AddressLine1	PO Box 1	PO Box 1
City	New York	New York
Country	USA	USA
HouseNumberHigh	60	9
HouseNumberLow	1	1
HouseNumberParity	B	B
MatchLevel	A	A
PostalCode	10002	10008
PostalCode.AddOn	0001	0001
ProcessedBy	USA	USA
RecordType	PostOfficeBox	PostOfficeBox
RecordType.Default
StateProvince	NY	NY
UnitNumberParity

Canadian Address Example

PostalCode:

A1A1A1

Preview Output:

Field Name	Output Record 1	Output Record 2
AddressLine1	LOWER BATTERY RD	LOWER BATTERY RD
City	ST. JOHN'S	ST. JOHN'S
Country	CAN	CAN
HouseNumberHigh	000003	000004 A
HouseNumberLow	000001	000002
HouseNumberParity	O	E
MatchLevel	A	A
PostalCode	A1A1A1	A1A1A1
ProcessedBy	CAN	CAN
RecordType	Normal	Normal
StateProvince	NL	NL

Resource URL

JSON endpoint:

http://server:port/rest/GetCandidateAddresses/results.json

https://OnDemandServer/rest/GetCandidateAddresses/results.json

XML endpoint:

http://server:port/rest/GetCandidateAddresses/results.xml

https://OnDemandServer/rest/GetCandidateAddresses/results.xml

http://server:port/soap/GetCandidateAddresses

https://OnDemandServer/soap/GetCandidateAddresses

For a list of Spectrum Technology Platform servers, see Connecting to Servers.

Example with JSON Response

The following example requests a JSON response:

http://myserver:8080/rest/GetCandidateAddresses/results.json?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY

https://spectrum.precisely.com/rest/GetCandidateAddresses/results.json?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY

The JSON returned by this request would be:

{"output_port": [
      {
      "ProcessedBy": "USA",
      "RecordType": "PostOfficeBox",
      "MatchLevel": "A",
      "AddressLine1": "PO Box 1",
      "HouseNumberLow": "1",
      "HouseNumberHigh": "60",
      "HouseNumberParity": "B",
      "UnitNumberLow": "",
      "UnitNumberHigh": "",
      "UnitNumberParity": " ",
      "FirmName": "",
      "City": "New York",
      "USUrbanName": "",
      "StateProvince": "NY",
      "PostalCode": "10002",
      "Country": "USA",
      "PostalCode.AddOn": "0001",
      "user_fields": []
   },
      {
      "ProcessedBy": "USA",
      "RecordType": "PostOfficeBox",
      "MatchLevel": "A",
      "AddressLine1": "PO Box 1",
      "HouseNumberLow": "1",
      "HouseNumberHigh": "9",
      "HouseNumberParity": "B",
      "UnitNumberLow": "",
      "UnitNumberHigh": "",
      "UnitNumberParity": " ",
      "FirmName": "",
      "City": "New York",
      "USUrbanName": "",
      "StateProvince": "NY",
      "PostalCode": "10008",
      "Country": "USA",
      "PostalCode.AddOn": "0001",
      "user_fields": []
   },
      {
      "ProcessedBy": "USA",
      "RecordType": "PostOfficeBox",
      "MatchLevel": "A",
      "AddressLine1": "PO Box 1",
      "HouseNumberLow": "1",
      "HouseNumberHigh": "60",
      "HouseNumberParity": "B",
      "UnitNumberLow": "",
      "UnitNumberHigh": "",
      "UnitNumberParity": " ",
      "FirmName": "",
      "City": "New York",
      "USUrbanName": "",
      "StateProvince": "NY",
      "PostalCode": "10009",
      "Country": "USA",
      "PostalCode.AddOn": "0001",
      "user_fields": []
   }
]}

Example with XML Response

The following example requests an XML response:

http://myserver:8080/rest/GetCandidateAddresses/results.xml?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY

https://spectrum.precisely.com/rest/GetCandidateAddresses/results.xml?Data.AddressLine1=P.O.+Box+1&Data.City=New+York&Data.StateProvince=NY

The XML returned by this request would be:

<ns2:xml.GetCandidateAddressesResponse xmlns:ns2="http://www.pb.com/spectrum/services/GetCandidateAddresses">
   <ns2:output_port>
      <ns2:Address>
         <ns2:ProcessedBy>USA</ns2:ProcessedBy>
         <ns2:RecordType>PostOfficeBox</ns2:RecordType>
         <ns2:MatchLevel>A</ns2:MatchLevel>
         <ns2:AddressLine1>PO Box 1</ns2:AddressLine1>
         <ns2:HouseNumberLow>1</ns2:HouseNumberLow>
         <ns2:HouseNumberHigh>60</ns2:HouseNumberHigh>
         <ns2:HouseNumberParity>B</ns2:HouseNumberParity>
         <ns2:UnitNumberLow/>
         <ns2:UnitNumberHigh/>
         <ns2:UnitNumberParity></ns2:UnitNumberParity>
         <ns2:FirmName/>
         <ns2:City>New York</ns2:City>
         <ns2:USUrbanName/>
         <ns2:StateProvince>NY</ns2:StateProvince>
         <ns2:PostalCode>10002</ns2:PostalCode>
         <ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn>
         <ns2:Country>USA</ns2:Country>
         <ns2:user_fields/>
      </ns2:Address>
      <ns2:Address>
         <ns2:ProcessedBy>USA</ns2:ProcessedBy>
         <ns2:RecordType>PostOfficeBox</ns2:RecordType>
         <ns2:MatchLevel>A</ns2:MatchLevel>
         <ns2:AddressLine1>PO Box 1</ns2:AddressLine1>
         <ns2:HouseNumberLow>1</ns2:HouseNumberLow>
         <ns2:HouseNumberHigh>9</ns2:HouseNumberHigh>
         <ns2:HouseNumberParity>B</ns2:HouseNumberParity>
         <ns2:UnitNumberLow/>
         <ns2:UnitNumberHigh/>
         <ns2:UnitNumberParity></ns2:UnitNumberParity>
         <ns2:FirmName/>
         <ns2:City>New York</ns2:City>
         <ns2:USUrbanName/>
         <ns2:StateProvince>NY</ns2:StateProvince>
         <ns2:PostalCode>10008</ns2:PostalCode>
         <ns2:PostalCode.AddOn>0001</ns2:PostalCode.AddOn>
         <ns2:Country>USA</ns2:Country>
         <ns2:user_fields/>
      </ns2:Address>
   </ns2:output_port>
</ns2:xml.GetCandidateAddressesResponse>

Example

The following shows a SOAP request:

<soapenv:Envelope
	xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:get="http://www.pb.com/spectrum/services/GetCandidateAddresses">
	<soapenv:Header/>
	<soapenv:Body>
		<get:GetCandidateAddressesRequest>
			<get:input_port>
				<get:Address>
					<!--Optional:-->
					<get:AddressLine1>P.O. Box 1</get:AddressLine1>
					<!--Optional:-->
					<get:AddressLine2></get:AddressLine2>
					<!--Optional:-->
					<get:AddressLine3></get:AddressLine3>
					<!--Optional:-->
					<get:AddressLine4></get:AddressLine4>
					<!--Optional:-->
					<get:AddressLine5></get:AddressLine5>
					<!--Optional:-->
					<get:City>New York</get:City>
					<!--Optional:-->
					<get:StateProvince>NY</get:StateProvince>
					<!--Optional:-->
					<get:PostalCode></get:PostalCode>
					<!--Optional:-->
					<get:Country></get:Country>
					<!--Optional:-->
					<get:FirmName></get:FirmName>
					<!--Optional:-->
					<get:USUrbanName></get:USUrbanName>
					<!--Optional:-->
					<get:user_fields>
						<get:user_field>
							<get:name></get:name>
							<get:value></get:value>
						</get:user_field>
					</get:user_fields>
				</get:Address>
			</get:input_port>
		</get:GetCandidateAddressesRequest>
	</soapenv:Body>
</soapenv:Envelope>

This would be the response:

Note: Empty response elements have been removed from this example. Only the first two candidate address are shown.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns3:GetCandidateAddressesResponse xmlns:ns2="www.pb.com/" xmlns:ns3="http://www.pb.com/spectrum/services/GetCandidateAddresses">
         <ns3:output_port>
            <ns3:Address>
               <ns3:ProcessedBy>USA</ns3:ProcessedBy>
               <ns3:RecordType>PostOfficeBox</ns3:RecordType>
               <ns3:MatchLevel>A</ns3:MatchLevel>
               <ns3:AddressLine1>PO Box 1</ns3:AddressLine1>
               <ns3:HouseNumberLow>1</ns3:HouseNumberLow>
               <ns3:HouseNumberHigh>60</ns3:HouseNumberHigh>
               <ns3:HouseNumberParity>B</ns3:HouseNumberParity>
               <ns3:City>New York</ns3:City>
               <ns3:StateProvince>NY</ns3:StateProvince>
               <ns3:PostalCode>10002</ns3:PostalCode>
               <ns3:PostalCode.AddOn>0001</ns3:PostalCode.AddOn>
               <ns3:Country>USA</ns3:Country>
            </ns3:Address>
            <ns3:Address>
               <ns3:ProcessedBy>USA</ns3:ProcessedBy>
               <ns3:RecordType>PostOfficeBox</ns3:RecordType>
               <ns3:MatchLevel>A</ns3:MatchLevel>
               <ns3:AddressLine1>PO Box 1</ns3:AddressLine1>
               <ns3:HouseNumberLow>1</ns3:HouseNumberLow>
               <ns3:HouseNumberHigh>9</ns3:HouseNumberHigh>
               <ns3:HouseNumberParity>B</ns3:HouseNumberParity>
               <ns3:City>New York</ns3:City>
               <ns3:StateProvince>NY</ns3:StateProvince>
               <ns3:PostalCode>10008</ns3:PostalCode>
               <ns3:PostalCode.AddOn>0001</ns3:PostalCode.AddOn>
               <ns3:Country>USA</ns3:Country>
            </ns3:Address>
         </ns3:output_port>
      </ns3:GetCandidateAddressesResponse>
   </soap:Body>
</soap:Envelope>