Developer Program

Ready to join the Developer Program? Join NOW FREE

Resources

Pickup

Code Samples for Pickup: Java (.zip) | PHP (.zip) | C# (.zip)

Get Pickup Availability – REST

Summary

Name:	Get Pickup Availability
Reason to Call:	To retrieve information on pickup availability and cut-off times available based on pickup location
Input:	Postal Code
Output:	true / false for pickup available, cut-off times
Error Examples:	Invalid Postal Code
Version history:	Release notes

Request Details

Request – Structure for Get Pickup Availability

Endpoint

GET https://XX/ad/pickup/pickupavailability/{postal code}
Replace...	With...
XX (Development)	ct.soa-gw.canadapost.ca
XX (Production)	soa-gw.canadapost.ca
{postal code}	the Postal Code of the desired Post Office

HTTP Headers

HTTP Header Variable	Value
Accept	application/vnd.cpc.pickup+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

Body

None

Request – Elements

The Postal Code is the only parameter required or allowed for the Get Pickup Availability service, as shown below.

Get Pickup Availability – REST – Request Parameters

Parameter
Name Type of
Parameter Description/Size/Format

Get Pickup Availability – REST – Request Parameters
Parameter Name	Type of Parameter	Description/Size/Format
{postal code}	Directly embedded in URI	Full Postal Code 6-character Postal Code in valid Postal Code format, e.g. A9A9A9. Note: If you wish to use Postal Codes with an embedded space (e.g. A9A 9A9), you must convert these spaces to %20 in your code before passing the value to the web service. The {postal code} is embedded in the URI as follows: `XX/ad/pickup/pickupavailability/{postal code}`

{postal code}

Directly embedded
in URI

Full Postal Code

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

Note: If you wish to use Postal Codes with an embedded space (e.g. A9A 9A9), you must convert these spaces to %20 in your code before passing the value to the web service.

The {postal code} is embedded in the URI as follows:

XX/ad/pickup/pickupavailability/{postal code}

Response Details

Response – Elements

Only simple types of response elements are shown in the table below. For complex types, see the diagram.

Get Pickup Availability – REST – Detailed View of Response Elements
Tag/Label	Description/Format
pickup-availability	The top level XML element of the response structure.
postal-code	Full Postal Code 7 character postal code in valid postal code format, (i.e. all capitalized and including an embedded space). i.e. A9A 9A9.
on-demand-cutoff	Time nn:nn (24 hour clock) expressed in local time of the specified postal code. Indicates the latest time that a pickup can be requested for the same day for parcels. Will be empty if on-demand-tour is false.
on-demand-tour	true \| false Indicates whether on demand pickups can be requested for the specific area.
scheduled-pickups-available	true \| false Indicates whether scheduled pickups are available to this postal code.

Response – Possible Error Responses

A correctly structured request may receive one of the following application error responses:

Code	Message
No_PostalCode_Provided	This is returned when a blank Postal Code is provided in the request.
Invalid_PostalCode_format	This is returned when the Postal Code provided does not pass a basic format check. (Note: the basic format check only confirms that there is a valid number of characters.)
No_Record_Found	This is returned when the system is unable to find information on the Postal Code that was provided. The most likely cause of this error is that an invalid Postal Code was provided.

Code

Message

No_PostalCode_Provided

This is returned when a blank Postal Code is provided in the request.

Invalid_PostalCode_format

This is returned when the Postal Code provided does not pass a basic format check.

(Note: the basic format check only confirms that there is a valid number of characters.)

No_Record_Found

This is returned when the system is unable to find information on the Postal Code that was provided. The most likely cause of this error is that an invalid Postal Code was provided.

Response – XML Diagram

Diagram of XML Response to Get Pickup Availability

Examples

Sample REST XML Request – Get Pickup Availability


  GET https://XX/ad/pickup/pickupavailability/K2B8J6

Sample REST XML Response – Get Pickup Availability


  
  

		<pickup-availability>
	
    
		<postal-code>K2B 8J6</postal-code>

		<on-demand-cutoff>16:00</on-demand-cutoff>

		<on-demand-tour>true</on-demand-tour>

		<prority-world-cutoff>14:00</prority-world-cutoff>

		<scheduled-pickups-available>true</scheduled-pickups-available>

	
		</pickup-availability>

Example error response


  
  
 <return>

    <error-list>

     <status-message>

       <code>No_Record_Found</code>

        <message></message>

      
    
    </error-list>

    </get-pickup-availability-response>

Sign in