Trouver un bureau de poste

Exemples de codes pour trouver un bureau de poste : Java (.zip) | PHP (.zip) | C# (.zip)

Obtenir le bureau de poste le plus près – Module REST

Résumé

Nom :

Obtenir le bureau de poste le plus près
Raison pour utiliser le
service :
  • Pour récupérer les renseignements sur les bureaux de poste les plus près d'un emplacement donné
  • Pour récupérer une liste de bureaux de poste offrant l'option de livraison directe à un bureau de poste
Données d'entrée :
  • Longitude et latitude
  • Code postal ou rue, ville et province de l'emplacement privilégié
  • Nombre maximal de bureaux de poste voulus dans la réponse
Données de sortie : Liste de bureaux de poste les plus près de l'emplacement précisé
Exemples d'erreurs : Code postal, ville ou province invalide
Historique des versions :

Notes de mise à jour

Détails sur la demande

Demande – Structure pour le service « Obtenir le bureau de poste le plus près »

Point final

GET https://XX/ot/address/office?postalCode={Code postal}&province={Province} &city={Ville}&streetName={Nom de rue}&maximum={Nombre maximal de bureaux}

Remplacez... Par...

XX (développement)

ct.soa-gw.canadapost.ca

XX (production)

soa-gw.canadapost.ca

{Code postal}

Code postal de l'emplacement à proximité duquel vous voulez trouver un bureau de poste

{Province}

Province dans laquelle vous souhaitez trouver des bureaux de poste

{Ville}

Ville dans laquelle vous souhaitez trouver des bureaux de poste

{Nom de rue}

Nom de la rue à proximité de laquelle vous voulez trouver un bureau de poste

{Nombre maximal de bureaux affichés}

Nombre maximal de bureaux de poste que vous souhaitez afficher

Nota : Le paramètre de requête « d2po=true » (le cas échéant) indique que seuls les bureaux de poste offrant l'option « Livrer au
bureau de poste » s’afficheront.

En-têtes HTTP

Variable des en-têtes HTTP

Valeur

Accept

application/vnd.cpc.postoffice+xml (Remarque : */* à la place de la valeur de l’en-tête affichera un message d’erreur)

Authorization

Basic {Encodage base64 du code d'usager:mot de passe}

Accept-language

en-CA ou fr-CA

Corps du message

Aucun

Demande – Paramètres de requête

Les paramètres de requête pour le service « Obtenir le bureau de poste le plus près » sont les suivants :

Obtenir le bureau de poste le plus près – Paramètres de requête de la demande
Nom du paramètre Type du paramètre Description

d2po

Paramètre de requête (Optionnel)

Vrai | Faux

La mention « Vrai » indique que vous voulez une liste de bureaux de poste acceptant la livraison de colis assortis de l'option « Livrer au bureau de poste ». Utilisez cette option lorsque vous voulez qu'un colis soit livré directement à un bureau de poste plutôt qu'à l'adresse d'un destinataire.

La mention « Faux » indique que vous voulez que tous les bureaux de poste soient inclus dans la liste. Ce paramètre de la demande de service doit être « Faux » lorsque vous cherchez des bureaux de poste où déposer des colis.

S’il manque le paramètre de requête, la mention « Faux » s’affiche par défaut.

Nota : Si vous n'utilisez pas les services Web pour créer des étiquettes d'expédition, lisez les exigences obligatoires pour la mise en œuvre de l'option « Livrer au bureau de poste ».

maximum

Paramètre de requête (Optionnel)

Indique le nombre maximal de bureaux de poste à afficher avec la réponse.

Le nombre maximal permis est de 50. La valeur par défaut est de 10.

Dans les emplacements éloignés, un nombre de bureaux de poste moins élevé que celui demandé peut s'afficher.

longitude

Paramètre de requête (Optionnel)

Si vous utilisez les données de longitude et de latitude pour définir l'emplacement, la longitude et la latitude doivent toutes deux être indiquées et tous les autres champs de recherche (postalCode, province, city et streetName) doivent être omis. (Si l'un de ces champs de recherche est présent, le système n'en tiendra pas compte.)

Le format compte 10 caractères.
[-]3.5
C'est-à-dire, jusqu'à trois chiffres avant la décimale et cinq chiffres après la décimale.
Exemple : -101.32354

latitude

Paramètre de requête (Optionnel)

Si vous utilisez les données de longitude et de latitude pour définir l'emplacement, la longitude et la latitude doivent toutes deux être indiquées et tous les autres champs de recherche (postalCode, province, city, et streetName) doivent être omis. (Si l'un de ces champs de recherche est présent, le système n'en tiendra pas compte.)

Le format compte 10 caractères.
[-]3.5
C'est-à-dire, jusqu'à trois chiffres avant la décimale et cinq chiffres après la décimale.
Exemple : 55.32354

Les champs de recherche suivants ne doivent être utilisés que si les paramètres de longitude et de latitude ne sont pas présents.

postalCode

Paramètre de requête (Optionnel)

Le code postal prime si des critères de recherche multiples sont fournis. Si le code postal et d'autres paramètres sont précisés, le code postal sera utilisé par l'algorithme de recherche et les autres paramètres seront ignorés.

Le format du code postal à six caractères est valide (p. ex. ?postalCode = A9A9A9).

Nota : Les codes postaux comptant sept caractères (avec une espace intégrée) sont également acceptés (p. ex. postalCode = A9A 9A9).

Tout ce qui n'est pas un code postal valide entraînera une erreur. (Par exemple, le format
« postalcode={blank} » entraînera une erreur.)

province

Paramètre de requête (Optionnel)

Si le code postal n'est pas précisé, la province et la ville doivent être fournies. Pour obtenir des renseignements pertinents, le nom de la ville doit être fourni avec celui de la province. Pour les municipalités plus importantes, une simple recherche par province et par ville peut afficher un sous-ensemble de bureaux de poste disponibles, mais il n'est pas garanti lesquels se trouveront dans le sous-ensemble.

Ainsi, pour les municipalités plus importantes, saisissez à la fois la province, la ville et la rue, ou, si vous voulez obtenir de meilleurs résultats, saisissez plutôt la latitude et la longitude ou le code postal.

(Code à deux caractères pour les provinces canadiennes – ISO 3166-2)

city

Paramètre de requête (Optionnel)

Si le code postal n'est pas précisé, la province et la ville doivent être fournies pour obtenir des renseignements pertinents. Pour les plus grandes municipalités, la province, la ville et la rue peuvent être requises.

streetName

Paramètre de requête (Optionnel)

Cet élément correspond au nom de rue seulement – sans le numéro de maison ou d'appartement (une recherche avec le numéro de maison ou d'appartement n'aura pas de succès). Le nom de la rue peut être un nom à plusieurs volets ayant des espaces intégrées.

Si la ville et la province sont précisées, le fait de fournir ce paramètre réduira la liste à un endroit plus précis dans la ville indiquée.

Pour les plus grandes municipalités, la liste peut ne pas s'afficher si le nom de la rue n'est pas fourni en plus de celui de la ville et de la province.

Demande – Éléments

Les éléments d'entrée XML ne sont pas nécessaires pour le service « Obtenir le bureau de poste le plus près ».

Détails de la réponse

Réponse – Éléments

Le tableau suivant décrit les éléments XML figurant dans la réponse à la demande d'obtention du bureau de poste le plus près. Pour obtenir la hiérarchie de la réponse, consultez le diagramme XML.

Obtenir le bureau de poste le plus près – Éléments de la réponse

Nom de l'élément

Type

Description

post-office-list

complexe

Élément XML de niveau supérieur pour la structure de réponse.

post-office

complexe

Occurrence (1 à N fois).

Correspond aux renseignements sur un seul bureau de poste.

address

complexe

Correspond aux renseignements sur l'adresse du bureau de poste.

city

simple

Municipalité dans laquelle se trouve le bureau de poste.

latitude

simple

Latitude du bureau de poste.

longitude

simple

Longitude du bureau de poste.

postal-code

simple

Code postal du bureau de poste.

province

simple

Province dans laquelle le bureau de poste est situé.

office-address

simple

Numéro et nom de rue pour un bureau de poste.

distance

simple

Distance (en km) entre le bureau de poste et l'endroit précisé dans la requête.

location

simple

Emplacement d'un bureau de poste. On l'utilise pour distinguer divers bureaux de poste qui ont des noms semblables.

name

simple

Nom attribué au bureau de poste.

office-id

simple

Numéro d'identification unique interne de Postes Canada attribué au bureau de poste. Ce numéro est nécessaire pour utiliser le service Web « Obtenir les détails d'un bureau de poste ».

Nota : Les zéros du début sont importants et doivent être inclus.

bilingual-designation

simple

Vrai | Faux

  • La mention « Vrai » indique que le bureau de poste fournit des services bilingues (français et anglais).
  • La mention « Faux » indique qu'il n'y a aucune désignation quant à la prestation de services bilingues. Elle n'indique pas une langue de service précise.

link

complexe

Cet élément représente un lien vers le service Web « Obtenir les détails d'un bureau de poste ».

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

Le lien compte les trois attributs suivants :

  1. href String. Il s'agit du point final pouvant être demandé à l'aide d'une requête GET (protocole HTTP) dans le but de récupérer de l'information.

  2. rel. String. Désigne l'objectif du lien et le type de renseignements qui y seront récupérés. Dans ce cas, la chaîne « rel="detail » indique que le lien sert à récupérer les détails sur le bureau de poste.

  3. media-type. Il s'agit d'une chaîne indiquant le format et la structure de toutes les données d'entrée supplémentaires qui sont nécessaires pour faire une demande de services Web. Il s'agit habituellement d'une chaîne désignant une version XML appropriée des services Web de Postes Canada pour les expéditions. La valeur de l'attribut media-type doit être incluse dans un en-tête
    « Accept » (protocole HTTP) lorsqu'il faut faire une demande à tout autre service désigné par l'attribut
    « href ».

Réponse – Diagramme XML

Obtenir le bureau de poste le plus près – Structure de la réponse XML

Obtenir le bureau de poste le plus près – Structure de la réponse XML

Réponse – Réponses d'erreur possibles

Code Message
E00010 Bureaux de poste non trouvés

Exemples

Exemple de demande XML selon le module REST – Obtenir le bureau de poste le plus près

GET https://XX/rs/postoffice?d2po=true&postalCode=K0J2M0&maximum=1

Exemple de réponse XML selon le module REST – Obtenir le bureau de poste le plus près

<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>
<link rel="detail" href="https://qa.ct.soa-gw.canadapost.ca/rs/postoffice/0000102978/detail" media-type=""></link>
</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>
<link rel="detail" href="https://qa.ct.soa-gw.canadapost.ca/rs/postoffice/0000313386/detail" media-type=""></link>
</post-office>
</post-office-list>