Documentation du Métamoteur

• Introduction
• Enregistrement
  • Création
  • Transmission de données multiples
  • Feedback
  • Modification / Suppression
  • Exemple de code PHP
• Requète / Consultation
• Régions disponibles

Introduction

Ce document décrit les interactions disponibles avec le métamoteur de partage des conditions de courses en montagne sur le Web. L'application n'est pas un site web classique mais un web service doté de fonctions d'insertion de l'information (« push » - réservé aux partenaires du service) et d'interrogation / consommation du service (« query » - ouvert au public).

Le service est accessible à l'adresse http://meta.camptocamp.org/

La page d'accueil accessible à cette adresse comporte un formulaire permettant d'obtenir facilement l'URL correspondant à une recherche selon les critères de son choix.

Une version "bac à sable" est également disponible pour les tests à l'adresse http://meta.camptocamp.org:8080/

PUSH (enregistrement)

L'URL de base de cette fonction est : http://meta.camptocamp.org/outings/push

URL de base "bac à sable" : http://meta.camptocamp.org:8080/outings/push

L'application prend alors en paramètre 3 inputs (méthode POST) :

• metaengine_user_id: id numérique du partenaire (préalablement configuré dans les fichiers de configuration sur le serveur)
• metaengine_user_key: clé associée au partenaire, sha1 d'une string associant le nom du partenaire et un mot clé (spécifiés dans les fichiers de configuration sur le serveur)
• metaengine_xml: un document XML, basé sur la structure définie par le fichier xml schema disponible à l'adresse http://meta.camptocamp.org/metaengineschema.xsd

Création

3 cas sont possibles et sont décrits ci-dessous. A noter que l'ordre des éléments XML est important.

Avec coordonnées lat/lon

Exemple de document XML transmis :

<?xml version="1.0" encoding="UTF-8"?>
<outings xmlns="http://meta.camptocamp.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://meta.camptocamp.org/metaengineschema.xsd">
    <outing>
        <name>Mont Blanc: Par les 3 Mont-Blanc</name>
        <geom>40.0446,-76.4131</geom>
        <elevation>4300</elevation>
        <date>2007-08-06</date>
        <lang>fr</lang>
        <activity>1</activity>
        <activity>5</activity>
        <activity>6</activity>
        <rating>très dur</rating>
        <facing>4</facing>
        <original_outing_id>42</original_outing_id>
        <url>http://example.com/sortie42.html</url>
    </outing>
</outings>

Les éléments XML à utiliser sont :

• <name> nom de la sortie. obligatoire
• <geom> coordonnées lat/lon du sommet, séparées par une virgule <geom>6.072,45.653</geom> Les objets géométriques utilisent par défaut le SRID 4326.
• <elevation> altitude du sommet en mètres
• <date> date de la sortie, au format yyyy-mm-dd. obligatoire
• <lang> langue de la description : code à 2 caractères selon la norme ISO 639-1. obligatoire
• <activity> identifiant numérique d'activité. On peut avoir autant d'éléments <activity> que nécessaire. obligatoire. Les activités disponibles sont:
  • 1: alpinisme
  • 2: canyon
  • 3: cascade glace
  • 4: escalade
  • 5: haute-montagne
  • 6: hors-piste
  • 7: randonnée pédestre
  • 8: raquette
  • 9: rocher
  • 10: skirando
  • 11: surf
  • 12: via-ferrata
  • 13: VTT
• <rating> niveau de difficulté champ libre
• <facing> identifiant numérique d'orientation (une seule valeur)
  • 0: (non définie)
  • 1: N
  • 2: NW
  • 3: W
  • 4: SW
  • 5: S
  • 6: SE
  • 7: E
  • 8: NE
• <original_outing_id> id de la sortie sur le site du partenaire. obligatoire
• <url> url pointant sur la sortie sur le site du partenaire. obligatoire

Avec l'id de la région (region_id)

L'id est l'id de région interne au métamoteur, l'utilisateur doit utiliser une grille pour connaître la correspondance entre un id de région dans un système (c2c, sngm) et l'id attribué en interne. Les régions actuellement intégrées au métamoteur sont décrites à la fin de ce document.

Exemple de document XML transmis :

<?xml version="1.0" encoding="UTF-8"?>
<outings xmlns="http://meta.camptocamp.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://meta.camptocamp.org/metaengineschema.xsd">
    <outing>
        <name>test name</name>
        <elevation>2452</elevation>
        <date>2007-08-06</date>
        <lang>fr</lang>
        <activity>1</activity>
        <activity>5</activity>
        <activity>10</activity>
        <rating>facile</rating>
        <facing>5</facing>
        <original_outing_id>42</original_outing_id>
        <url>http://example.com/sortie42.html</url>
        <region_code>2</region_code>
    </outing>
</outings>

En plus des éléments XML décrits dans la section précédente on peut alors utiliser l'élément suivant :

• <region_code> code interne de la région

Avec un nom de région

Si le partenaire ne peut pas associer de coordonnées géographiques à sa sortie ou de massif prédéfini dans la base de données du métamoteur, il peut spécifier un nom de massif libre. Cette façon de faire n'est pas recommandée car elle réduit l'efficacité du filtrage géographique mais est tout de même fournie afin de ne pas trop prétériter les partenaires ne disposant pas d'informations plus précises.

Exemple de document XML transmis :

<?xml version="1.0" encoding="UTF-8"?>
<outings xmlns="http://meta.camptocamp.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://meta.camptocamp.org/metaengineschema.xsd">
    <outing>
        <name>test name</name>
        <elevation>2452</elevation>
        <date>2007-08-06</date>
        <lang>fr</lang>
        <activity>1</activity>
        <activity>5</activity>
        <activity>10</activity>
        <rating>très dur</rating>
        <facing>6</facing>
        <original_outing_id>42</original_outing_id>
        <url>http://example.com/sortie42.html</url>
        <region_name>Mont Blanc</region_name>
    </outing>
</outings>

L'élément XML suivant est ajouté par rapport aux systèmes précédents :

• <region_name> nom de la région. champ libre

Transmission de données multiples

Il est possible de transmettre ("pusher") plusieurs sorties à la fois en utilisant la syntaxe suivante :

<?xml version="1.0" encoding="UTF-8"?>
<outings xmlns="http://meta.camptocamp.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://meta.camptocamp.org/metaengineschema.xsd">
    <outing>
        ...(outing 1)...
    </outing>
    <outing>
        ...(outing 2)...
    </outing>
    <outing>
        ...(outing 3)...
    </outing>
</outings>

A noter que le traitement est interrompu en cas d'erreur dans une sortie. Validez le xml à l'aide du schéma (http://meta.camptocamp.org/metaengineschema.xsd) avant de pusher plusieurs sorties en même temps.

Feedback

Le script revoie un document XML :

<?xml version="1.0"?>
<metaengine_result>
  <status>1</status>
</metaengine_result>

• status = 1, tout est ok
• status = 0, une erreur est survenue

<metaengine_result>
  <status>0</status>
  <errors>
    <error>
      <outing_counter>5</outing_counter>
      <outing_id>42</outing_id>
      <error_message>missing mandatory element (activity_ids)</error_message>
    </error>
    <error>
      <outing_counter>8</outing_counter>
      <outing_id>45</outing_id>
      <error_message>An outing with the same original_outing_id already exist for the system selected</error_message>
    </error>
  </errors>
</metaengine_result>

• "outing_counter" est un compteur interne. "5" signifie qu'une erreur est survenue dans la 5eme sortie dans la liste de sorties qui ont été traitées.
• "outing_id" correspond à l'"original_outing_id" de la sortie en question.
• "errmsg": le message d'erreur

Lorsqu'une erreur survient, la sortie incriminée est ignorée et le script passe au traitement de la sortie suivante.

Modification / Suppression

Pour modifier ou supprimer une sortie, il faut spécifier un "status". La valeur du paramètre "original_outing_id" est utilisée pour identifier la sortie. L'ordre des éléments est important.

<?xml version="1.0" encoding="UTF-8"?>
<outings xmlns="http://meta.camptocamp.org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://meta.camptocamp.org/metaengineschema.xsd">
    <outing>
        <name>test name</name>
        <elevation>2452</elevation>
        <date>2007-08-06</date>
        <lang>fr</lang>
        <activity>1</activity>
        <activity>5</activity>
        <activity>10</activity>
        <rating>très dur</rating>
        <facing>5</facing>
        <original_outing_id>42</original_outing_id>
        <url>http://example.com/sortie42.html</url>
        <region_code>4</region_code>
        <status>1</status>
    </outing>
</outings>

• <id> id de la sortie a modifier
• <status>
  • 0: ajout (par défaut)
  • 1: modification
    • 2: suppression

Seul le partenaire ayant créé la sortie peut la supprimer.

Exemple de code PHP permettant de pousser les données requises vers le metamoteur

Le script ci dessous est basé sur Curl : http://www.php.net/curl

<?php
$post = 'metaengine_user_id=' . $votre_id . 
        '&metaengine_user_key=' . $votre_clef . 
        '&metaengine_xml=' . urlencode($votre_xml);

$ch = curl_init();

// Push vers le metamoteur de test
curl_setopt($ch, CURLOPT_URL, "http://meta.camptocamp.org:8080/outings/push");
curl_setopt($ch, CURLOPT_PORT, 8080);

// Push vers le metamoteur de production :
// curl_setopt($ch, CURLOPT_URL, "http://meta.camptocamp.org/outings/push");

curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

echo curl_exec($ch);
curl_close($ch);

PULL (query)

Cette fonction est accessible à l'adresse suivante : http://meta.camptocamp.org/outings/query?parameters1=value11(,value12,...)(&parameters2=value21(,value22,...))...

A noter d'ailleurs que l'adresse par défaut du métamoteur http://meta.camptocamp.org/outings correspond à une requête sans filtrage.

L'URL "bac à sable" est http://meta.camptocamp.org:8080/outings/query

Des critères de filtre peuvent être transmis via des paramètres GET de l'URL.

La recherche multicritère est stricte (operateur 'AND'). Plusieurs critères peuvent être utilisés en même temps. Tous les critères acceptent une ou plusieurs valeurs séparées par des virgules. Il faut au minimum un critère et une valeur associée.

Les critères sont les suivants :

• mot clé dans le nom de la sortie:
  • outing_name=foo
  • outing_name=foo,bar,test
• nom de la région:
  • region_name=region1
  • region_name=region1,region2,region3
  • région id:
  • region_id=2
  • region_id=2,3
• system id (partenaire id):
  • system_id=1 (c2c)
  • system_id=1,2 (c2c & sngm)
• date:
  • outing_date=2007-08-06 (du 2007-08-06 et plus récent)
  • outing_date=2007-08-06,2007-08-09 (du 2007-08-06 au 2007-08-09)
• langue:
  • outing_lang=it
  • outing_lang=fr,it
• activité:
  • activity_ids=3
  • activity_ids=3,7,11
• ordre des résultats:
  • orderby=outing_name
  • orderby=region_name
  • orderby=region_id
  • orderby=system_id
  • orderby=outing_date
• limite (la valeur par défaut est de 50):
  • limit=10

Le résultat est formaté suivant la norme RSS 2.0. La page de requête par défaut (aucun critère spécifié) est dotée d'un cache de 5 minutes.

Liste des régions disponibles

La liste suivante indique les régions actuellement intégrées dans le métamoteur. Le premier identifiant est le numéro de document sur camptocamp.org, le second est l'identifiant interne de région pour le métamoteur.

      14420: 1 # Adamello
      14421: 2 # Alpes Vaudoises
      14454: 3 # Alpi Giulie
      14461: 4 # Alpi Liguri
      14422: 5 # Alpi Ticinesi - Conches - Goms
      14462: 6 # Appennino centrale
      14458: 7 # Appennino meridionale
      14467: 8 # Appennino settentrionale
      14469: 9 # Ariège - Cardós - Andorra
      14443: 10 # Arlberg - Silvretta
      14399: 11 # Bauges
      14400: 12 # Beaufortain
      14398: 13 # Belledonne
      14442: 14 # Berner Alpen
      14417: 15 # Bornes-Aravis
      14423: 16 # Bündner Oberland - Adula - Ticino E
      14416: 17 # Pyrénées Orientales
      14415: 18 # Capcir Corbières
      14451: 19 # Carinthia
      14424: 20 # Cerces - Thabor - Mont Cenis
      14411: 21 # Chablais
      14401: 22 # Chartreuse
      14448: 23 # Chiemgauer Alpen - Kitzbühler Alpen
      14478: 24 # Corse
      14449: 25 # Dachstein
      14402: 26 # Dévoluy
      14456: 27 # Dolomiti centrale
      14444: 28 # Dolomiti occidentale
      14455: 29 # Dolomiti orientale
      14403: 30 # Ecrins
      14425: 31 # Engadin - Disgrazia
      14414: 32 # Gavarnie - Ordesa - Guara
      14418: 33 # Genevois - Jura S
      14426: 34 # Glarner Alpen
      14427: 35 # Gran Paradiso
      14404: 36 # Haut Giffre - Aiguilles Rouges
      14405: 37 # Jura
      14453: 38 # Karawanken
      14452: 39 # Karnische Alpen
      14406: 40 # Lauzière
      14441: 41 # Lechtaler Alpen - Wetterstein - Karwendel
      14460: 42 # Lubéron - Baronnies - Saoû
      14466: 43 # Mercantour - Argentera
      14410: 44 # Mont Blanc
      14470: 45 # Montes Ibericos
      14450: 46 # Niedere Tauern
      14428: 47 # Orobie
      14429: 48 # Ortles
      14430: 49 # Ötztal
      14465: 50 # Pelat - Préalpes de Castellane
      14471: 51 # Picos de Europa - Cantabrica
      14464: 52 # Préalpes Dignoises
      14431: 53 # Préalpes Fribourgeoises et Bernoises
      14463: 54 # Provence
      14447: 55 # Pustresi - Hohe Tauern
      14413: 56 # Pyrénées Occidentales
      14432: 57 # Queyras N - Briançonnais - Cozie
      14433: 58 # Queyras S - Parpaillon - Ubaye - Oronaye
      14407: 59 # Grandes Rousses
      14477: 60 # Sardegna
      14474: 61 # Scotland
      14476: 62 # Sicilia
      14472: 63 # Sierra de Gredos
      14473: 64 # Sierra de Guadarrama
      14468: 65 # Sierra Nevada - Sistema Penibico
      14446: 66 # Steirische Alpen
      14434: 67 # Stubaïer Alpen - Sarntaler Alpen
      14408: 68 # Taillefer
      14440: 69 # Toggenburg - Appenzell
      14435: 70 # Urner Alpen
      14436: 71 # Valais E - Alpes Pennines E
      14437: 72 # Valais W - Alpes Pennines W
      14412: 73 # Aure Néouvielle - Posets Maladeta - Aigüestortes
      14409: 74 # Vanoise
      14459: 75 # Vercors
      14438: 76 # Vorarlberg - Allgauer Alpen
      14419: 77 # Vosges
      14475: 78 # Wales
      14445: 79 # Wienner Alpen
      14439: 80 # Zentral Graubünden
      14457: 81 # Zillertaler Alpen