La Ville d’Ottawa appuie l’adoption de la norme DonnéesOuvertes311 GeoReport v2. Pour en savoir plus sur DonnéesOuvertes311, consulter Open311.org et la page wiki sur la spécification de DonnéesOuvertes311 GeoReport v2. Le présent document aidera les développeurs à utiliser cette spécification de l’API en leur décrivant ses aspects compatibles et incompatibles ainsi que certaines nuances propres à son utilisation dans le cas de la Ville d’Ottawa.
Il est actuellement possible de présenter les types de demande de service suivants :
- Les services des déchets solides
- L'entretien des routes
- Les graffitis
- Les services des règlements municipaux
- Les parcs et les forêts
- Le stationnement
- L'éclairage des rues
Processus de développement
Les applications créées à l’aide du format DonnéesOuvertes311 GeoReport v2 de la Ville d’Ottawa doivent être mises à l’essai au moyen des outils ci-dessous :
Notez que l'API de test ne crée pas de cas dans un système dorsal et doit être utilisée pour tester uniquement les réponses API.
En ce qui concerne l’élaboration du service POST, une clé de contrôle est disponible pour ceux qui n’ont pas de clé pour le système de production. Veuillez utiliser la clé suivante : upxH1uGMCboY3qrXKGRmKWdYaxha
Lorsque vous utilisez une clé API pour accéder au système de production, les demandes de service affichées seront soumises aux systèmes dorsaux de production ; Veuillez ne pas soumettre les informations d'essai en production. La soumission des données d'essai peut entraîner la révocation de votre clé API.
Lorsque les applications sont prêtes pour la production, elles doivent utiliser les éléments suivants:
Rendu à la phase de production, il ne devrait plus y avoir de tests. Tous les paramètres et toutes les fonctionnalités des applications devraient avoir été testés lors du développement et avant la demande d’une clé et la mise en service.
- Les personnes qui détiennent les clés (ou les développeurs) doivent informer SOWeb@ottawa.ca au sujet de leur plan d’essai (date et heure, demandes de service qui seront présentées).
- SOWeb@ottawa.ca confirmera l’approbation du plan.
- Les personnes qui détiennent les clés doivent utiliser les valeurs suivantes pour leur cas d’essai :
- First name: Test
- Last Name: Test
- Client address id: __9BQ1OJ
- Address: 100 CONSTELLATION DR, NEPEAN K2G6J8
- Telephone: 6135802424
- Email: testing@ottawa.ca
- Description: Test case please close
- Les détenteurs de clés doivent aviser SOWeb@ottawa.ca une fois que les cas auront été soumis avec succès.
Application - Exigences
Pour s’assurer de la prestation des services municipaux et promouvoir une expérience positive pour les utilisateurs d’applications tierces, la Ville demande aux développeurs de satisfaire à certaines exigences obligatoires. Les privilèges d'accès aux services API et aux données sont accordés à la discrétion de la Ville et peuvent être assortis de restrictions ou résiliés, conformément aux conditions d’utilisation.
Exigences que les développeurs doivent obligatoirement respecter
- Les applications tierces doivent rendre leur déclaration de confidentialité visible aux utilisateurs.
- Pour obtenir une clé API, les développeurs doivent fournir leurs coordonnées. La Ville se réserve le droit de les diffuser ou de les publier, et acheminera aux développeurs toutes les requêtes se rapportant aux applications tierces.
- Les applications doivent soumettre à la Ville les coordonnées (nom, adresse civique et adresse de courriel) du client ou de la personne qui fait la demande de service, là où c’est obligatoire. Toute application qui soumet des données qui ne viennent pas du client, telles des coordonnées par défaut, verra sa clé API révoquée.
- L’utilisation des marques de commerce de la Ville, comme les logos, etc., est strictement interdite.
Exigences que nous recommandons aux développeurs de respecter
- Les applications devraient utiliser l’état d’avancement fourni par la Ville pour les suivis des demandes de service.
- Les développeurs devraient envisager de doter leurs applications d’une interface en anglais et d’une interface en français.
- Les développeurs devraient envisager d’intégrer des mécanismes d’accessibilité dans la conception de l’interface en se basant sur les lignes directrices de l’initiative W3C (WCAG AA).
- Afin d’assurer la traçabilité de la demande de service d’un utilisateur qui veut en faire le suivi directement auprès de la Ville, les applications devraient fournir le numéro de demande de service émis par la Ville à l’utilisateur. Toutefois, cela n’empêche aucunement l’application de fournir son propre numéro de suivi à l’utilisateur, en plus du numéro de demande de service de la Ville.
La spécification de DonnéesOuvertes311 GeoReport v2 et la Ville d’Ottawa
Découverte de services
Les URL de base pour la découverte de services de la Ville d’Ottawa vont comme suit :
Compatibilité des formats
La Ville d’Ottawa accepte les formats XML et JSON.
Définitions et points divers
jurisdiction_id
La Ville d’Ottawa ignore le paramètre « jurisdiction_id ».
Langue
La Ville d’Ottawa accepte les deux langues officielles dans l’API; lorsqu’il est utilisé, l’en-tête requête « Locale » affichant la valeur « en-CA » ou « fr-CA » l’emporte sur l’en-tête par défaut « AcceptLanguage ». En l’absence de l’en-tête requête « Locale », le portail se rabattra sur l’en-tête par défaut « Accept-Language » de l’utilisateur. S’il n’y pas de paramètre d’en-tête, celui-ci sera réglé à « Locale » avec la valeur « en-CA ».
Taille des champs
La spécification de DonnéesOuvertes311 GeoReport v2 ne permet pas de préciser la taille des champs; cependant, les systèmes dorsaux internes imposent certaines limites qu’il faut respecter :
Champs connus
- first_name : 35
- last_name : 40
- email : 60
- description : 2 000
- phone : 11 (les tirets et parenthèses disparaîtront; il doit s’agir d’un numéro valide en Amérique du Nord)
- media_url : 255
- cde_extension : 6
Champs d’attribut, par type
- string: 40
- number: 40
- text: 2000
- singlevaluelist: 80
- multivaluelist: 80
- datetime: 25
À noter que ces limites pourraient changer.
Méthodes API compatibles
GET Service List
Cette méthode est acceptée.
GET Service Definition
Cette méthode est acceptée.
POST Service Request
Cette méthode est acceptée, sous les réserves suivantes :
Validation des adresses
La Ville d’Ottawa accepte les trois méthodes d’adressage de la spécification de DonnéesOuvertes311 GeoReport v2 (address_id, address_string, et binôme de latitude et de longitude). La méthode privilégiée pour les adresses de service est le binôme latitude et longitude, sinon, on favorisera un identifiant valide d’adresse municipale (cela s’applique aux adresses de service [address_id] ainsi qu’aux adresses de clients [client_adress_id ou client_adress_id_req]). Les chaînes de caractères (string) sont aussi acceptées pour les adresses, mais conduisent à davantage d’erreurs en raison des divergences dans ce que tapent les utilisateurs. Les développeurs d’applications doivent veiller à ce que les adresses soumises soient valides; pour les aider dans cette tâche, la Ville d’Ottawa offre un service Web d’adressage :
Suivre les étapes ci-dessous pour garantir la validité de l’adresse municipale dans les champs « address_id », « client_address_id », ou « client_address_id_req » :
- Entrer l’URL suivante (en insérant la chaîne de caractères de l’adresse de l’utilisateur; exemple en gras) :https://city-of-ottawa-dev.apigee.net/gis/v1/findAddressCandidates?SingleLine=100+Constellation+DR&outFields=User_fld&f=json
- La réponse devrait être comme suit (l’élément en gras est l’identifiant de l’adresse [address_id ]) :{"spatialReference":{"wkid":102100,"latestWkid":3857},"candidates":[{"address":"100 CONSTELLATION DR","location":{"x":-8434021.1488476545,"y":5676573.4154919367,"z":-100000},"score":100,"attributes":{"User_fld":"__9BQ1OJ"}},...(il peut y avoir plus de résultats)]}
- Vérifier que l’adresse qui vous est retournée correspond bien à ce que l’utilisateur a entré, puis utiliser l’identifiant de l’adresse que donne le service (la valeur donnée à l’élément « User_fld ») pour remplir les champs du formulaire (« address_id », « client_address_id » ou « client_address_id_req »).
Coordonnées des utilisateurs finaux
Certains des services énumérés sur le portail de la Ville d’Ottawa ont besoin de renseignements sur le client, comme ses coordonnées ou son adresse personnelle, auquel cas ce sera indiqué dans la description du service. Prendre note des attributs suivants dans les définitions de services :
- contact_info_req Cet attribut indique que les coordonnées du client (prénom [first_name], nom [last_name], n o de téléphone [phone] et courriel [email]) sont exigées pour la demande de service.
- client_address_id_req et client_address_string_req Cet attribut indique que l’adresse du client est exigée pour la demande de service. Les exigences relatives à l’adresse du client peuvent être satisfaites de l’une des deux façons suivantes; vous avez le choix de fournir une adresse postale de la Ville d’Ottawa et de l’insérer dans le paramètre « client_address_string_req », ou d’extraire un identifiant d’adresse de la Ville d’Ottawa au moyen du service d’adressage et de l’insérer dans le paramètre « client_address_id_req ».
- Si vous choisissez d’utiliser une adresse postale, l’interface de programmation d’applications (API) validera le paramètre « client_address_string_req » au meilleur de ses capacités et pourrait produire une erreur de validation s’il ne parvient pas à trouver l’adresse fournie.
- Si vous choisissez d’utiliser un identifiant d’adresse, ce dernier peut être obtenu à l’aide du service d’adressage comme il est indiqué à la section validation des adresses.
- client_address_id et client_address_string Cet attribut indique que l’adresse du client est facultative pour la demande de service. Si vous choisissez de fournir ce renseignement, veuillez suivre les mêmes instructions que pour les attributs client_address_id_req et client_address_string_req
Si l’information requise n’est pas reçue, l’application à l’origine de la demande recevra une erreur de validation.
Champs de la définition du service.
- Les noms de champs (élément « code ») extraits de la définition du service doivent être encapsulés comme suit dans vos demandes, conformément à la spécification de GeoReport v2 attribute[] (attribute[][] pour les types de données siglevaluelist et multivaluelist) [voir http://wiki.open311.org/GeoReport_v2/#postservice-request sous les éléments « Required Arguments » et « Attribute »].
GET service_request_id from a token
Cette méthode n’est pas actuellement acceptée.
GET service requests
Cette méthode est acceptée, sous les réserves suivantes :
- Seuls les types de demandes de service définies à la méthode GET Service List sont disponibles pour cette méthode.
- S’attendre à une attente d’au moins cinq minutes après l’envoi de la demande de service pour pouvoir la récupérer à l’aide de la méthode GET Service Requests.
- Suivant la spécification de DonnéesOuvertes311 GeoReport v2, la limite par défaut pour les requêtes est une période de 90 jours ou les 1 000 premières demandes renvoyées, selon la plus petite de ces deux limites; la période couverte peut se situer dans les deux (2) dernières années.
- Les renseignements sur l’adresse seront transmis sous forme de renseignements sur le quartier (nom et numéro du quartier) ou de paires de coordonnées de latitude et de longitude associées à une adresse de service, en fonction du type de demande de service (voir l’annexe).
GET service request
Cette méthode est acceptée, sous les réserves suivantes :
- Seuls les types de demandes de service définies à la méthode GET Service List sont disponibles pour cette méthode.
- S’attendre à une attente d’au moins cinq minutes après l’envoi de la demande de service pour pouvoir la récupérer à l’aide de la méthode GET Service Request.
- En plus de l’argument obligatoire service_request_id, il est possible d’ajouter l’argument facultatif pour obtenir d’autres renseignements sur l’adresse outre l’information sur le quartier.
GET service requests par région géographique spécifique
Il est possible d’obtenir une liste de demandes de service créées dans une région géographique spécifique en inscrivant deux ensembles de coordonnées de latitude et de longitude dans votre requête. Les paramètres de la requête sont définis comme suit :
- query_location_lat_1 : coordonnée de latitude supérieure gauche
- query_location_lon_1 : coordonnée de longitude supérieure gauche
- query_location_lat_2 : coordonnée de latitude inférieure droite
- query_location_lon_2 : coordonnée de longitude inférieure droite
Exemple de requête : https://city-of-ottawa-dev.apigee.net/open311/v2/requests.xml?query_location_lat_1=45.3463453&query_location_lon_1=-75.8255661&query_location_lat_2=45.287005&query_location_lon_2=-75.716325
GET service requests par heure de mise à jour
Il est possible d’obtenir une liste de demandes de service mises à jour à partir d’une date et d’une heure spécifiques. Le paramètre de requête est défini comme suit :
- updated_datetime : doit être mis en forme conformément à un sous-ensemble commun de la norme ISO 8601. L’information sur le fuseau horaire (soit « Z », qui signifie le temps universel coordonné, ou une différence de temps par rapport au temps universel coordonné exprimé dans le format HH:MM) doit être incluse.
Exemple de requête : https://city-of-ottawa-dev.apigee.net/open311/v2/requests.xml?updated_datetime=2019-03-01T01:00:00-04:00
Erreurs
La description des erreurs à la validation des entrées s’articulera comme suit :
- Étiquette (nom du champ) message d’erreur
Les noms de champs pourraient être présentés sous forme de liste séparée par des virgules.
Exemple XML
<?xml version="1.0" encoding="utf-8"?>
<errors>
<error>
<code>400</code>
<description>> Le binôme latitude et longitude (lat,long) ne correspond pas à une adresse ou intersection valide.</description>
</error>
</errors>
Exemple JSON
[{"code":400,"description":"Le binôme latitude et longitude (lat,long) ne correspond pas à une adresse ou intersection valide."}]
Coordonnées
Si vous avez des questions sur le format DonnéesOuvertes311 GeoReport v2 de la Ville d’Ottawa, veuillez communiquer avec SOWeb@ottawa.ca.
Annexe
Types de demandes de service avec latitude et longitude affichées
- 2000040-1 Stationner ou arrêter dans une voie cyclable
- 2000046-1 Distributrices Payez et affichez
- 2000081-1 Puisards de rue
- 2000088-1 Graffiti – propriété publique – offensant
- 2000089-1 Graffiti – propriété publique – vandalisme
- 2000107-1 Terrain de baseball ayant besoin d’entretien
- 2000109-1 Sentier ayant besoin d’entretien dans un parc municipal
- 2000111-1 Herbe ayant besoin d’entretien dans un parc municipal
- 2000111-2 Panais sauvage, herbe à puce ou berce du Caucase dans un parc municipal
- 2000112-1 Poubelles dans des parcs
- 2000116-1 Chariot d’achat abandonné dans un parc municipal
- 2000123-1 Arbuste ou buissons ayant besoin d’entretien dans un parc municipal
- 2000154-1 Fossés
- 2000154-2 Panais sauvage, herbe à puce ou berce du Caucase dans des fossés
- 2000158-1 Espace entre la chaussée et le trottoir (servitude)
- 2000159-1 Bordure ou caniveau
- 2000161-1 Panais sauvage, herbe à puce ou berce du Caucase dans la zone entre les voies de circulation (terre-plein central)
- 2000162-1 Entretien des routes – Opérations générales
- 2000162-2 Chariot d’achat abandonné
- 2000162-3 Animal mort sur la route
- 2000163-1 Accotement en gravier
- 2000163-2 Panais sauvage, herbe à puce ou berce du Caucase sur le trottoir ou sur l’accotement
- 2000164-1 Entretien général des routes
- 2000164-2 Nid de poule
- 2000165-1 Entretien général des trottoirs
- 2000165-2 Entretien hivernal des trottoirs
- 2000166-1 Poubelle en bordure de la route
- 2000186-1 Éclairage de rue
- 2031035-1 Graffiti – OC Transpo
Types de demandes de service avec quartier affiché
- 2000031-1 Stationnement pour handicapés
- 2000031-2 Borne fontaine ou route
- 2000031-3 Véhicule non autorisé stationné dans votre place
- 2000032-1 Intersection
- 2000033-1 Stationnement – voies et allées publiques
- 2000034-1 Parc municipal
- 2000035-1 Zone de stationnement interdit
- 2000036-1 Zone d’arrêt interdit
- 2000037-1 Stationnement de nuit en hiver – zone restreinte
- 2000038-1 Rue – limite de temps dépassée
- 2000039-1 Sur le trottoir
- 2000039-2 Trop loin de la bordure (entrave à la circulation)
- 2000068-1 Chariot d’achat abandonné sur le terrain d’un immeuble de la Ville d’Ottawa
- 2000069-1 Chariot d’achat abandonné sur une propriété d’OC Transpo
- 2000099-1 Graffiti – propriété privée – offensant
- 2000099-2 Graffiti – propriété privée – vandalisme
- 2000141-1 Obtenir tous les bacs
- 2000142-1 Obtenir une nouvelle boîte noire
- 2000144-1 Obtenir une nouvelle boîte bleue
- 2000148-1 Obtenir un nouveau bac vert
- 2000149-1 Obtenir un nouveau bac pour la cuisine
- 2000157-1 Propriété endommagée par un véhicule de la Ville
- 2000173-1 Maisons – Collecte des boîtes noires
- 2000174-1 Maisons – Collecte des boîtes bleues
- 2000176-1 Commande d’un calendrier de la collecte
- 2000177-1 Sapins de Noël
- 2000178-1 Collecte des déchets
- 2000180-1 Collecte des bacs verts
- 2000197-1 Programme spécial
- 2000341-1 Arbres de la Ville – Évaluation de santé
- 2000342-1 Arbres de la Ville – Identification du propriétaire
- 2000344-1 Arbres de la Ville – Retrait des broussailles et du bois
- 2000353-1 Arbres de la Ville – Infestation par les insectes
- 2000354-1 Arbres de la Ville – Retrait de souches
- 2000365-1 Arbres de la Ville – Entretien de nouveaux arbres
- 2000379-1 Arbres de la Ville – Le Fonds des arbres
- 2003000-1 Bruit : machine
- 2003001-1 Bruit : alarme de voiture
- 2003002-1 Bruit : chantier de construction
- 2003003-1 Bruit : camion de livraison
- 2003004-1 Bruit : ordures ménagères
- 2003006-1 Bruit : tapage
- 2003009-1 Bruit : cris
- 2003014-1 Chien auparavant en liberté
- 2003015-1 Aboiements
- 2003018-1 Chien dans un parc
- 2003019-1 Chien non enregistré
- 2003020-1 Problème de pitbull
- 2003022-1 Chat non enregistré
- 2003023-1 Chat perturbant
- 2003025-1 Animal exotique interdit
- 2003030-1 Entretien de propriété privée – Extérieur du bâtiment
- 2003031-1 Entretien de propriété privée – Intérieur du bâtiment
- 2003032-1 Entretien de propriété privée – Inspection de locaux commerciaux
- 2003034-1 Entretien de propriété privée – Véhicule abandonné
- 2003035-1 Entretien de propriété privée – Ascenseurs
- 2003036-1 Entretien de propriété privée – Débris et déchets à l’extérieur
- 2003038-1 Entretien de propriété privée – Herbe et herbe longue
- 2003048-1 Entretien de propriété privée – Chariot d’achat abandonné
- 2003053-1 Animal de compagnie perdu
- 2003054-1 Trop d’animaux
- 2030713-1 Infraction à une ordonnance de musellement
- 2030714-1 Infraction au règlement « Suivez-les, pelle en main »
- 2030759-1 Véhicule surdimensionné
- 2030760-1 Stationnement dans les cours avant
- 2030764-1 Usage de tabac dans des installations ou des propriétés de la Ville
- 2030765-1 Usage de tabac dans une aire commune
- 2030766-1 Usage de tabac dans un hôpital ou un établissement de soins de longue durée
- 2030767-1 Usage de tabac dans un restaurant, un bar ou sur une terrasse
- 2030768-1 Usage de tabac dans une école
- 2030769-1 Usage de la chicha ou du houka
- 2030770-1 Vente de tabac à des mineurs
- 2030771-1 Infraction relative à l’affichage des détaillants de tabac
- 2030772-1 Détaillant de tabac – Demande de matériel à afficher
- 2030773-1 Infraction relative au tabagisme sur les lieux de travail
- 2031040-1 Demande de bacs de recyclage – Nouvelle résidence
