• 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.

• Longitude and latitude
• Postal Code or street, city and province of the preferred location
• Maximum number of Post Offices desired in the response

XX (Development)

ct.soa-gw.canadapost.ca

XX (Production)

soa-gw.canadapost.ca

{postal code}

the Postal Code of the location you want the Post Office to be near

{province}

the province you wish Post Offices in

{city}

the city you wish Post Offices in

{street name}

the street name that you wish to find Post Offices near

{maximum office returned}

the maximum Post Offices that you wish to have returned

Note: The d2po=true query parameter (if present) indicates that only Post Offices that support the "Deliver to Post Office" delivery option will be returned.

Accept

application/vnd.cpc.postoffice+xml (Note: */* in place of the header value will return an error)

Authorization

Basic {Base64 encoding of userid:password}

Accept-language

en-CA or fr-CA

d2po

Query Parameter (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 call parameter should be false when looking for Post Offices from which to drop off parcels.

If the query 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.

maximum

Query Parameter (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.

longitude

Query Parameter (Optional)

If you use longitude and latitude to define the location, both longitude and latitude must be present and all other search fields (postalCode, province, city, and streetName) 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

Query Parameter (Optional)

If you use longitude and latitude to define the location, both longitude and latitude must be present and all other search fields (postalCode, province, city, and streetName) 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.

postalCode

Query Parameter (Optional)

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

6-character Postal Code in valid Postal Code format, e.g. ?postalCode=A9A9A9.

Note: 7 characters (with an embedded space) are also accepted, e.g. postalCode=A9A 9A9

Anything other than a valid Postal Code will produce an error. (e.g. postalcode={blank} will produce an error).

province

Query Parameter (Optional)

If Postal Code is not specified both Province and City should be provided. To get meaningful information, city should be provided along with province. For larger municipalities, a simple province and city search may return a subset of the available Post Offices, and 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/longitude or postalCode

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

city

Query Parameter (Optional)

If Postal Code is not specified, both Province and City should be provided to obtain meaningful information. For larger municipalities all of Province, City and Street may be required.

streetName

Query Parameter (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 might not be returned if the Street Name is not provided in addition to the City and Province attributes.

post-office-list

complex

The top level xml element for the response structure.

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.

link

complex

This element represents a link to the Get Post Office Detail web service.

e.g. <link href="https://XXX/rs/postoffice/123456/detail
rel="detail"
media-type="application/vnd.cpc.postoffice+xml"/>

The link has three attributes as follows.

1. href String. The endpoint that can be called using an HTTP GET to retrieve the information.


2. rel. String. This indicates the purpose of the link and the type of information that will be retrieved. In this case, rel="detail" indicates that the link is to retrieve details about the Post Office.


3. media-type. This is a string indicating the format and structure of any additional input data that is required when invoking the web services. This is usually a string indicating an appropriate version of Canada Post shipping web services XML. The value of the media-type attribute should be included as an HTTP Accept header in any of the calls to other services pointed to by the href.