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

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

Response – XML Diagram

Diagram of XML Response to Get Pickup Availability

Figure 2: 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>