wiki:Geonol/API_REST/poi.kml

poi.kml

Cette URL est un service web renvoyant un flux d'organismes géolocalisés.

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

  • balloon_style (int, default=0) : si le paramètre vaut 1, la balise <BalloonStyle> est ajoutée au résultat pour chaque <Placemark>. Elle contient la mise en forme HTML de la bulle qui s'affiche lorsqu'on clique sur un point d'intérêt.
  • category (str, multiple) : catégorie(s) de l'organisme. La recherche est faite sur l'union de toutes les catégories fournies, le cas échéant.
  • category_tag (str, multiple) : tag de l'une des catégories de l'organisme. Les catégories pouvant être taggés, ce paramètre permet de rechercher tous les organismes dont l'une des catégories est taggée par la valeur spécifiée. La recherche est faite sur l'union de tous les tags fournis, le cas échéant.
  • center (str) : définit un point autour duquel rechercher les organismes. La chaîne doit se composer de deux nombres flottants séparés par une virgule url-encodée (%2C). Le premier nombre est la longitude, le second la latitude. Les décimales sont séparées par un point. Les coordonnées sont exprimées dans le système géodésique WGS84.
  • format (str, default="geonol") : indique quel format utiliser pour générer le fichier KML. Cf la section « Formats » ci-dessous.
  • limit (int, default=10, min=1, max=100) : nombre maximum d'éléments renvoyés
  • 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é.
  • where (str) : nom de la commune à laquelle appartient l'organisme tel que retourné par l' « autocompleter des territoires ».

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

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

  • paramètre center seul : les organismes renvoyés sont situés physiquement autour du point spécifié.
  • paramètre where seul : les organismes renvoyés sont autour du centre de la commune spécifiée (le centre étant l'emplacement de la mairie).
  • paramètres center et where : les organismes renvoyés sont situés physiquement autour du point spécifié. Le paramètre where est utilisé uniquement pour préciser si un organisme est compétent sur la commune correspondant au where.

Les paramètres doivent être des chaînes de caractères « url-encodées ».

Format

Chaque format définit une liste de champs à afficher.

Les balises sont affichées uniquement si la donnée est disponible.

Voici les formats disponibles et les champs qu'ils affichent :

  • all (par défaut) : adresse
  • mobidroits : addresse, numéros de téléphone, numéros de fax, emails, URL(s) du(des) site(s) web, horaires d'ouverture

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 id="commune-coordinates" (optionnel) : ce premier point définit le centre de la commune recherchée. Ce n'est pas un organisme. Il apparaît uniquement si le paramètre de recherche « where » a été utilisé.
  • Placemark (multiple) : définit un organisme. L'attribut 'id' est l'identifiant unique de l'organisme.
    • name : nom de l'organisme
    • Point : coordonnées géographiques de l'organisme (ordre: longitude,latitude)
    • 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.
    • phoneNumber (optionnel, multiple) : numéro(s) de téléphone ou de fax de l'organisme selon que la valeur commence par "tel: " ou par "fax:".
    • ExtendedData (optionnel) : Données supplémentaires pour chaque Placemark
      • <Data name="accuracy"> (optionnel) : précision du géocodage de l'adresse, selon http://code.google.com/intl/fr-FR/apis/maps/documentation/javascript/v2/reference.html#GGeoAddressAccuracy
      • <Data name="emails"> (optionnel, multiple) : adresse(s) email de l'organisme, séparées par une virgule s'il y en a plusieurs.
      • <Data name="web-site-urls"> (optionnel, multiple) : URL(s) du(des) site(s) web de l'organisme, séparées par une virgule s'il y en a plusieurs.
      • <Data name="opening-hours"> (optionnel) : horaires d'ouverture de l'organisme.
      • <Data name="is-competent"> (optionnel) : compétence de l'organisme pour la commune recherchée. Cette donnée apparaît uniquement si le paramètre de recherche « where » a été utilisé. 0 signifie non compétent, et 1 signifie compétent. Si le paramètre de recherche « where » a été utilisé, et que la donnée is-competent n'est pas renvoyée, cela signifie que la compétence de l'organisme est inconnue pour cette commune.
    • 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, son adresse au format hcard (http://microformats.org/wiki/hcard) (inclue les numéros de téléphone, fax et adresses email), ses horaires d'ouverture et l'accuracy (cf ci-dessus). De plus, si l'organisme provient d'un annuaire qui a été indexé et que l'URL source est connue, la bulle contient un lien vers la page source de l'organisme (lien profond). Attention : 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

Affichage d'un fichier KML dans Google Maps :

http://maps.google.fr?q=http://xxx/file.kml

Exemple :

Last modified 7 years ago Last modified on Nov 10, 2010, 11:40:30 AM