GetCandidateAddresses - Spectrum_OnDemand - addressing - web_services - Latest

Spectrum OnDemand Web Services (REST)

Product type
Software
Portfolio
Verify
Product family
Spectrum
Product
Spectrum > Geocoding > Enterprise Tax
Spectrum > Web Services
Spectrum > Spatial > Spectrum Spatial
Spectrum > Spectrum Platform
Spectrum > Quality > Addressing
Spectrum > Quality > Spectrum Quality
Spectrum > Spatial > Spectrum Spatial Insights
Spectrum > Discovery
Spectrum OnDemand
Spectrum > Dataflow Designer
Spectrum > Spatial > Spectrum Spatial Analyst
Spectrum > Quality > Context Graph
Version
Latest
Language
English
Product name
Spectrum OnDemand
Title
Spectrum OnDemand Web Services (REST)
Copyright
2024
First publish date
2006
ft:lastEdition
2024-07-17
ft:lastPublication
2024-07-17T23:23:16.481321

GetCandidateAddresses returns a list of addresses that are considered matches for a given input address. GetCandidateAddresses 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 ValidateAddress and the results for that same address returned by GetCandidateAddresses. If you experience inconsistent results, it is likely because you set the performance tuning setting in ValidateAddress to a value other than 100. To obtain consistent results between GetCandidateAddresses and ValidateAddress, set the performance tuning option to 100.

Note: By default, GetCandidateAddresses does not match to individual house numbers. Rather, it uses house number ranges for each street. After GetCandidateAddresses 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 ValidateAddress 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.

GetCandidateAddresses is part of Spectrum Universal Address.

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

For a list of Spectrum OnDemand servers, see Connecting to Spectrum OnDemand 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>