Usage

Here's the detailed overview of the methods contained in this wrapper.

See how to use to get started and get yourself familiar with how the wrapper works.

Rating

Here there will be overviews of the methods that are combined in the rating block on Canada Post API.

get_rates

get_rates(
    origin_postal_code: str,
    destination: Destination,
    promo_code: str = None,
    quote_type: Literal[
        "commercial", "counter"
    ] = "commercial",
    expected_mailing_date: datetime = None,
    options: list[Option] = None,
    parcel_characteristics: ParcelCharacteristics = None,
    unpackaged: bool = False,
    mailing_tube: bool = False,
    oversized: bool = False,
    services: list[
        Literal[
            "DOM.RP",
            "DOM.EP",
            "DOM.XP",
            "DOM.XP.CERT",
            "DOM.PC",
            "DOM.LIB",
            "USA.EP",
            "USA.SP.AIR",
            "USA.TP",
            "USA.TP.LVM",
            "USA.XP",
            "INT.XP",
            "INT.IP.AIR",
            "INT.IP.SURF",
            "INT.SP.AIR",
            "INT.SP.SURF",
            "INT.TP",
        ]
    ] = None,
) -> list[Rate] | None

Function to get rates for a shipping based on the provided arguments.

Parameters:

Name	Type	Description	Default
`origin_postal_code`	`str`	Postal Code from which the parcel will be sent. Format ANANAN (only accepted with uppercase)	required
`destination`	`Destination`	Defines the destination of the parcel.	required
`promo_code`	`str`	If you have a promotional discount code, enter it here. The discount amount will be returned in the response under the adjustment structure.	`None`
`quote_type`	`Literal['commercial', 'counter']`	Either commercial or counter. "commercial" will return the discounted price for the commercial customer or Solutions for Small Business member. "counter" will return the regular price paid by consumers. Defaults to "commercial" if not specified.	`"commercial"`
`expected_mailing_date`	`datetime`	The expected mailing date for the parcel. This date is used in calculations of the expected delivery date, however all rate quotes are based on the current system date.	`None`
`options`	`list[Option]`	Structure containing the list of options desired for the shipment.	`None`
`parcel_characteristics`	`ParcelCharacteristics`	Details of the parcel such as weight and dimensions.	`None`
`unpackaged`	`bool`	Indicates that the parcel will be unpackaged (e.g. tires).	`False`
`mailing_tube`	`bool`	Indicates that the object will be shipped in a mailing tube.	`False`
`oversized`	`bool`	Indicates that the object has oversized dimensions. Automatically set correctly if dimensions are provided.	`False`
`services`	`list[Literal['DOM.RP', 'DOM.EP', 'DOM.XP', 'DOM.XP.CERT', 'DOM.PC', 'DOM.LIB', 'USA.EP', 'USA.SP.AIR', 'USA.TP', 'USA.TP.LVM', 'USA.XP', 'INT.XP', 'INT.IP.AIR', 'INT.IP.SURF', 'INT.SP.AIR', 'INT.SP.SURF', 'INT.TP']]`	List of services to be used for the shipment.	`None`

Returns:

Type	Description
`list[Rate] or None`	List of rates or None.

Examples:

>>> from py_canada_post.client import PyCanadaPost
>>> from py_canada_post.services.rating.types import Destination, DomesticDestination, Option, ParcelCharacteristics
>>>
>>> customer_number = 123456789
>>> api_key = "your_api_key"
>>> contract_id = 987654321
>>>
>>> py_canada_post = PyCanadaPost(
>>>     customer_number=customer_number,
>>>     api_key=api_key,
>>>     contract_id=contract_id
>>> )
>>>
>>> rates = py_canada_post.rating.rates.get_rates(
>>>     origin_postal_code="E4M8S3",
>>>     destination=Destination(
>>>         domestic=DomesticDestination(
>>>             postal_code="T3Z1C8"
>>>         )
>>>     ),
>>>     promo_code="YOUR_PROMO_CODE",
>>>     quote_type="commercial",
>>>     expected_mailing_date=datetime(2023, 10, 1),
>>>     options=[Option(option_code="SO", option_amount=5.0)],
>>>     parcel_characteristics=ParcelCharacteristics(
>>>         weight=23.5
>>>     ),
>>>     unpackaged=True,
>>>     mailing_tube=True,
>>>     oversized=True,
>>>     services=["DOM.RP"]
>>> )
>>> print(rates)

discover_services

discover_services(
    country_code: str,
    origin_postal_code: str = None,
    destination_postal_code: str = None,
) -> list[Service] | None

Function to discover services based on the country code, origin postal code, destination postal code and contract number.

Parameters:

Name	Type	Description	Default
`country_code`	`str`	Country code in a 2-letter format (e.g. JP, CA, US).	required
`origin_postal_code`	`str`	Origin postal code where the package will be sent from.	`None`
`destination_postal_code`	`str`	Destination postal code where the package will be delivered to.	`None`

Returns:

Type	Description
`list[Service] or None`	List of services or None.

Examples:

>>> from py_canada_post.client import PyCanadaPost
>>>
>>> customer_number = 123456789
>>> api_key = "your_api_key"
>>> contract_id = 987654321
>>>
>>> py_canada_post = PyCanadaPost(
>>>     customer_number=customer_number,
>>>     api_key=api_key,
>>>     contract_id=contract_id
>>> )
>>> services = py_canada_post.rating.services.discover_services(
>>>     country_code="CA",
>>>     origin_postal_code="E4M8S3",
>>>     destination_postal_code="T3Z1C8"
>>> )
>>> print(services)