Find a Post Office

Code Samples for Find a Post Office: Java (.zip) | PHP (.zip) | C# (.zip)

Get Nearest Post Office – SOAP

Summary

Name:

Get Nearest Post Office
Reason to Call:
  • To retrieve information on Post Offices nearest to a given location.
  • To retrieve a list of Post Offices that support the option for direct delivery to a Post Office.
Input:
  • Longitude and latitude
  • Postal Code or street, city and province of the preferred location
  • Maximum number of Post Offices desired in the response
Output: A list of Post Offices nearest to the specified location
Error Examples: Invalid Postal Code, city or province.
Version history: Release notes

Call Details

WSDL: postoffice.wsdl
Endpoint (Development): https://ct.soa-gw.canadapost.ca/rs/soap/postoffice
Endpoint (Production): https://soa-gw.canadapost.ca/rs/soap/postoffice
Namespace: http://www.canadapost.ca/ws/soap/postoffice
Operation: GetNearestPostOffice

SOAP Body

This section describes the XML input elements to this service. For the hierarchical structure, see the XML diagram.

Get Nearest Post Office – Request Elements
Element Name Type Required / Optional Description

get-nearest-post-office-request

complex

required

The top level XML element for the request input information.

locale

simple

optional

Indicates your language preference for receiving error messages.

EN = English
FR = French

If no value is provided, the default language is English.

maximum

simple

optional

Indicates the maximum number of Post Offices to return with the response.

The maximum allowed value is 50. The default value is 10.

In remote locations, fewer Post Offices than requested may be returned.

search-data

complex

required

The structure that contains the elements for searching for the nearest Post Office.

d2po

simple

optional

true | false

True indicates that you want a list of Post Offices that accept the "Deliver to Post Office" delivery of parcels. Use this when you want the parcel to be delivered directly to a Post Office rather than to the recipient’s address.

False indicates that you want all Post Offices included in the list. This element should be false when looking for Post Offices from which to drop off parcels.

If the d2po parameter is missing, it defaults to false.

Note: If you’re not using web services to create shipping labels, read mandatory requirements for implementing Deliver to Post Office.

longitude

simple

optional

If you use longitude and latitude to define the location, both longitude and latitude must be present and all other search fields to (postal-code, province, city, and street-name) should be omitted. (If any of these other search fields are present, they will be ignored)

Format is 10 characters of the form:
[-]3.5
i.e. up to 3 digits before the decimal and 5 digits after the decimal
e.g. -101.32354

latitude

simple

optional

If you use longitude and latitude to define the location, both longitude and latitude must be present and all other search fields to (postal-code, province, city, and street-name) should be omitted. (If any of these other search fields are present, they will be ignored)

Format is 10 characters of the form:
[-]3.5
i.e. up to 3 digits before the decimal and 5 digits after the decimal
e.g. 55.32354

The following search fields should only be used if longitude and latitude are NOT present.

postal-code

simple

optional

6-character Postal Code in valid Postal Code format.

Example: A9A9A9.

Note: 7 characters (with an embedded space) are also accepted. Example: A9A 9A9

Postal Code takes precedence if multiple search criteria are provided. If Postal Code and other search elements are specified, Postal Code will be used by the search algorithm and other search elements will be ignored.

Anything other than a valid Postal Code will produce an error. (e.g., a blank Postal Code will produce an error).

city

simple

optional

If Postal Code is not specified, both province and city should be provided to obtain meaningful information.

For larger municipalities, a province-city search may return a subset of the available Post Offices, but there is no guarantee as to which ones will be in the subset.

Thus, for larger municipalities, either all of province, city and street may be required, or, for the best results, use latitude and longitude or postal-code.

province

simple

optional

(2-character representation of Canadian provinces - ISO 3166-2)

If Postal Code is not specified both province and city should be provided.

Note: To get meaningful information, city should be provided along with province. For larger municipalities, all of province, city and street-name may be required.

street-name

simple

optional

This element represents the street name only—without the house or apartment number (a search with house or apartment number will not be successful). Street name can be a multi-part name with embedded spaces.

If city and province are specified, provision of this parameter will refine the list to a more specific location in the city indicated.

For larger municipalities a list may not be returned if the street name is not provided in addition to the city and province attributes.

Request – XML Diagram

Get Nearest Post Office – Structure of the XML Request

Get Nearest Post Office – Structure of the XML Request

Response Details

Response – Elements

The following table describes the XML elements in the response to Get Nearest Post Office. For the hierarchy of the response, see the
XML diagram.

Get Nearest Post Office – Response Elements

Element Name

Type

Description

get-nearest-post-office-response

complex

This is the top level of the XML structure for the response.

It will either contain the results of a successful completion or the error structure.

post-office-list

complex

Contains the list of post offices.

post-office

complex

May occur 1 .. N times.

Represents the information about a single Post Office.

address

complex

Represents the information on the address of the Post Office.

city

simple

Municipality in which the Post Office is located.

latitude

simple

The latitude of the Post Office.

longitude

simple

The longitude of the Post Office.

postal-code

simple

The Postal Code of the Post Office.

province

simple

The province where the Post Office is located.

office-address

simple

Street number and name for a Post Office.

distance

simple

The distance (in km) to the Post Office from the location specified in the query.

location

simple

The location of a Post Office. This is used to distinguish among various Post Offices that have similar names.

name

simple

The name assigned to the Post Office.

office-id

simple

The internal Canada Post assigned unique identification number for the Post Office. This number is necessary for calling the Get Post Office Detail web service.

Note: leading zeroes are significant and should be included.

bilingual-designation

simple

true | false

  • True indicates that the Post Office provides bilingual services (English and French).
  • False indicates no designation for the provision of bilingual services. False does not indicate a specific language of service.

Response – XML Diagram

Response – Possible Error Responses

The response to error conditions for this web service follows the standard SOAP error response approach used for all Canada Post web services. For more information, see SOAP Fundamentals of Canada Post Web Services.

Possible error messages for this service include the following:

Code Description
E00010 No Post Offices found.

Examples

Sample SOAP XML Request – Get Nearest Post Office

<get-nearest-post-office-request>
<locale>EN</locale>
<maximum>2</maximum>
<search-data>
<d2po>true</d2po>
<longitude>-79.3496</longitude>
<latitude>43.7054</latitude>
</search-data>
</get-nearest-post-office-request>

Sample SOAP XML Response – Get Nearest Post Office

<get-nearest-post-office-response>
<post-office-list>
<post-office>
<address>
<city>OTTAWA</city>
<latitude>45.3545</latitude>
<longitude>-75.8061</longitude>
<postal-code>K2B7K0</postal-code>
<province>ON</province>
<office-address>3080 CARLING AVE</office-address>
</address>
<distance>0.65</distance>
<location>CRYSTAL BEACH PO</location>
<name>SHOPPERS DRUG MART # 1387</name>
<office-id>0000102978</office-id>
<bilingual-designation>true</bilingual-designation>
</post-office>
<post-office>
<address>
<city>OTTAWA</city>
<latitude>45.3284</latitude>
<longitude>-75.8196</longitude>
<postal-code>K2H8Z0</postal-code>
<province>ON</province>
<office-address>3659 RICHMOND RD</office-address>
</address>
<distance>1.94</distance>
<location>NEPEAN H PO</location>
<name>NEPEAN H PO</name>
<office-id>0000313386</office-id>
<bilingual-designation>true</bilingual-designation>
</post-office>
</post-office-list>
</get-nearest-post-office-response>