wiki:Geonol/API_REST

Version 22 (modified by http://cbenz.myopenid.com/, 8 years ago) (diff)

--

API REST

L'API REST de Geonol permet de rechercher des POI dans la base de données.

La requête est faite par l'URL : http://annuaire.comarquage.fr/rest/poi.kml?query_string, où query_string est remplacé par les paramètres documentés ci-dessous.

La réponse est au format KML : http://code.google.com/intl/fr-FR/apis/kml/documentation/.

Paramètres de la requête

  • bbox (str) : définit un rectangle (bounding-box) dans lequel rechercher les organismes. La chaîne doit se composer de 4 nombres flottants séparés par une virgule. Les décimales sont séparées par un point. Les deux premiers nombres définissent le coin en bas à gauche du rectangle, et les deux derniers le coin en haut à droite. Les coordonnées sont exprimées dans le système géodésique WGS84.
  • q (str) : recherche sur les différents champs de l'organisme : nom, adresse, etc. (fulltext search). Cette recherche est « approximative » : elle porte sur les radicaux des mots.
  • start (int, défaut=0) : numéro d'ordre du premier organisme retourné. Si start=0, aucun décalage n'est effectué.
  • tag (str, multiple) : type de l'organisme ou mot-clé associé. La recherche est faite sur l'intersection de tous les tags fournis, le cas échéant.
  • where (str) : nom de la commune à laquelle appartient l'organisme tel que retourné par l'« autocompleter ».

Tous les paramètres sont optionnels et peuvent être combinés.

Deux paramètres, bbox et where, définissent l'emplacement des organismes pour une recherche. Plusieurs cas sont possibles :

  • paramètre bbox seul : les organismes renvoyés sont situés physiquement à l'intérieur du rectangle spécifié
  • paramètre where seul : les organismes renvoyés sont autour du centre de la commune spécifiée
  • paramètres bbox et where : les organismes renvoyés sont situés physiquement à l'intérieur du rectangle spécifié, et les organismes compétents sur la commune spécifiée sont renvoyés en premier.

Réponse

Les balises suivantes du format KML sont utilisées. Les balises sont toujours définies, sauf mention « optionnel ».

  • name : nom du document
  • ExtendedData : contient les informations relatives à la pagination
    • <Data name="date"> : date et heure à laquelle le document a été généré, au format ISO 8601, YYYY-MM-DDTHH:MM:SS.mmmmmm ou YYYY-MM-DDTHH:MM:SS si microsecondes=0
    • <Data name="start"> : même valeur que celle fournie dans la requête
    • <Data name="count"> : nombre d'organismes total trouvés par la recherche, sans tenir compte de la pagination
  • Placemark (multiple) : définit un organisme. L'attribut 'id' est l'identifiant unique de l'organisme
    • name : nom de l'organisme
    • address (optionnel) : adresse de l'organisme, formatée en chaîne de caractères d'une seule ligne, sans balise HTML. Les lignes de l'adresse sont séparées par des virgules.
    • Point (optionnel) : coordonnées géographiques de l'organisme (ordre: longitude,latitude)
    • Style : contient le code HTML de l'info-bulle associée à l'organisme, au format utilisé par Google Maps pour rendre la couche KML. Contient le nom de l'organisme et son adresse au format hcard (http://microformats.org/wiki/hcard). Si l'organisme provient d'un annuaire qui a été indexé et que l'URL source est connue, le nom de l'organisme est un lien vers la page source de l'organisme (lien profond). Tel que mentionné dans la documentation de référence du format KML (cf ci-dessus), la chaîne de caractères "$[name]" est utilisée dans le code HTML, et doit être remplacée par le nom de l'organisme.

Exemples de requêtes

Exemple de réponse KML

cf Geonol/API_REST/KMLResponseExample

Intégration dans Google Maps

Exemple d'affichage d'un fichier KML généré par l'annuaire dans Google Maps :