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.
BFLF	simple	optional	true \| false True indicates that customer wants a list of Post Offices that accept the "Box Free Label" delivery of parcels. False indicates that customer wants all Post Offices included in the list and not just the ones with BFLF service. If the query parameter is missing, it defaults to false.
tonight	simple	optional	true \| false Same as equivalent REST parameter.
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

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

Get Nearest Post Office – Structure of the XML Response

View full-size image

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>

Sign in

Resources