Skip to content

Addressing Service

Jump to bottom
Jamie Thompson edited this page Dec 4, 2020 · 3 revisions

http://api.despatchbay.com/soap/v16/addressing?wsdl

The Addressing Service allows you to search for UK addresses which can subsequently be fed into the Shipping Service to create labels. Each address is uniquely identified by an AddressKey

Warning: Usage of the Addressing Service is for genuine customers of Despatch Bay only. API usage is monitored and any usage of the Addressing Service which is not accompanied by genuine Shipping Service usage will be subject to account closure. If you would like to discuss your usage of the Addressing Service please contact us

Changes: No changes to the Addressing Service have been introduced between v15 and v16.

Methods

Note: The Addressing Service methods work only with UK addresses identified by Royal Mail postcodes. This includes The Isle of Man (IM postcodes), Channel Islands (JE & GY postcodes) and Northern Ireland (BT postcodes) but excludes the Republic of Ireland.

Whilst Despatch Bay will accept Eircodes for Republic of Ireland addresses, there is currently no Eircode lookup or validation in Despatch Bay. If you would like to discuss Eircode support please get in touch

FindAddress

The FindAddress method searches for a single address using a postcode and property number/name.

Note: Searching using a property name can yield differing results. This method is best suited for use with addresses identified by a property number.

<message name="FindAddressRequest">
  <part name="postcode" type="xsd:string"/>
  <part name="property" type="xsd:string"/>
</message>
  <message name="FindAddressResponse">
  <part name="return" type="tns:AddressType"/>
</message>

...

<operation name="FindAddress">
  <documentation>
    Returns an address by searching on a given postcode/property combination
  </documentation>
  <input message="tns:FindAddressRequest"/>
  <output message="tns:FindAddressResponse"/>
</operation>

Tip: If you simply want to find all possible addresses for a given postcode then use the GetAddressKeysByPostcode method.

Input Output
(String) postcode
(String) property 		AddressType

GetAddressByKey

The GetAddressByKey type returns an address matching a specified AddressKey.

<message name="GetAddressByKeyRequest">
  <part name="key" type="xsd:string"/>
</message>
<message name="GetAddressByKeyResponse">
  <part name="return" type="tns:AddressType"/>
</message>

...

<operation name="GetAddressByKey">
  <documentation>
    Returns the address relating to a given [`AddressKey`](#addresskeytype) (as returned by [`GetAddressKeysByPostcode`](#getaddresskeysbypostcode))
  </documentation>
  <input message="tns:GetAddressByKeyRequest"/>
  <output message="tns:GetAddressByKeyResponse"/>
</operation>
Input Output
(String) key AddressType

GetAddressKeysByPostcode

The GetAddressyKeysByPostcode method returns an array of AddressKeyType objects for a given postcode, each with a unstructured single-line string representation of the address. Each AddressKeyType.Key can subsequently be passed into the GetAddressByKey method in order to obtain a structured AddressType object which can be used in conjunction with the Shipping Service.

<message name="GetAddressKeysByPostcodeRequest">
  <part name="postcode" type="xsd:string"/>
</message>
<message name="GetAddressKeysByPostcodeResponse">
  <part name="return" type="tns:ArrayOfAddressKeyType"/>
</message>

...

<operation name="GetAddressKeysByPostcode">
  <documentation>
    Returns all known addresses (with addressKeys) for a given postcode
  </documentation>
  <input message="tns:GetAddressKeysByPostcodeRequest"/>
  <output message="tns:GetAddressKeysByPostcodeResponse"/>
</operation>
Input Output
(String) postcode ArrayOfAddressKeyType

Types

AddressType

The AddressType object represents a postal address. Addresses returned by the Addressing Service are always UK addresses (ISO 3166-1 alpha-2 code GB)

<xsd:complexType name="AddressType">
  <xsd:all>
    <xsd:element name="CompanyName" type="xsd:string" minOccurs="0" maxOccurs="1"/>
    <xsd:element name="Street" type="xsd:string" minOccurs="1" maxOccurs="1"/>
    <xsd:element name="Locality" type="xsd:string" minOccurs="0" maxOccurs="1"/>
    <xsd:element name="TownCity" type="xsd:string" minOccurs="1" maxOccurs="1"/>
    <xsd:element name="County" type="xsd:string" minOccurs="0" maxOccurs="1"/>
    <xsd:element name="PostalCode" type="xsd:string" minOccurs="1" maxOccurs="1"/>
    <xsd:element name="CountryCode" type="xsd:string" minOccurs="1" maxOccurs="1"/>
  </xsd:all>
</xsd:complexType>
Element Name Type Description
CompanyName String Company/Organisation name
Street String First line of street address
Locality String Second line of street address
TownCity String Town or city name
County String County
PostalCode String Postcode
CountryCode String ISO 3166-1 alpha-2 code. Always GB for addresses returned by the Addressing Service

AddressKeyType

<xsd:complexType name="AddressKeyType">
  <xsd:all>
    <xsd:element name="Key" type="xsd:string"/>
    <xsd:element name="Address" type="xsd:string"/>
  </xsd:all>
</xsd:complexType>
Element Name Type Description
Key String Unique key identifying the address. Keys can be passed into GetAddressByKey to obtain a structured AddressType object.
Example: GU104AE1004
Address String a single-line unstructured string representation of the address

ArrayOfAddressKeyType

ArrayOfAddressKeyType is an array of AddressKeyType objects

<xsd:complexType name="ArrayOfAddressKeyType">
  <xsd:complexContent>
    <xsd:restriction base="SOAP-ENC:Array">
      <xsd:attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="tns:AddressKeyType[]"/>
    </xsd:restriction>
  </xsd:complexContent>
</xsd:complexType>

Clone this wiki locally