API V1

Nouveau : API SityTour V2

Accéder à la documentation de l’API V2
 

Cette API est dépréciée

Cette interface de programmation est uniquement maintenue pour des raisons de compatibilité et sera bientôt retirée. Les utilisateurs sont invités à passer dès maintenant à l'API V2.

Merci de votre compréhension


L’API SityAPI

SityTour propose un ensemble d’outil de diffusion de circuits de randonnées (applications mobiles, sorties papier, site web).
SityAPI propose aux webmasters d’intégrer directement les circuits de randonnées au sein de leur site web ou leur outil de gestion.

La seule condition au bon fonctionnement est de disposer d’un espace d’au moins 600px de large sur votre site.

En fonction des besoins et des capacités techniques du site sur lequel les randonnées doivent être intégrées, deux types d’intégration sont proposés :

Intégration Iframe

Méthode d’intégration la plus simple : Un simple copier-coller de script permet l’intégration des données dans la plupart des CMS ou sites web.

Avantages
* Simplicité d’utilisation
* Rapidité, peu de configuration
* Intégration possible dans n’importe quel site web

Inconvénients
* Pas d’indexation : Les randonnées intégrées ne seront pas répertoriées dans les différents moteurs de recherche
* Rigidité : Seules des options de base sont disponibles (filtrage fixe)
* Style préétabli : Les randonnées intégrées sont présentées au sein d’une charte graphique neutre.

Intégration PHP

Cette méthode consiste à place un script d’intégration PHP au sein du site client. Lors de chaque requête le script est exécuté sur le serveur du client et celui-ci traduit la requête utilisateur en requête compréhensible par le serveur SityAPI. Les résultats sont en suite affichés au sein du site client de manière totalement transparente, donnant l’illusion que les résultats sont produits par le site client lui même.

Avantages
* Cohésion avec le site client. Les résultats sont affichés selon la charte graphique du site client
* Flexibilité : différents filtres peuvent être préétablis
* Extensible : Le client peut séparer les résultats en plusieurs pages avec des filtres préétablis (p.ex : toutes les randonnées en vélo, à cheval, etc.) ou encore y adjoindre son propre moteur de recherche
* Les résultats sont lus et indexés par les moteurs de recherche

Inconvénients
* Le site client doit être capable d’exécuter du code PHP.
* L’intégration peut nécessiter un temps un petit peu plus important.
* En fonction de la complexité de la charte graphique et de la feuille de style utilisée, les résultats affichés peuvent nécessiter quelques adaptations.

Appels directs à SityAPI

L’utilisateur dispose de la possibilité de programmer ses propres appels à l’API et ainsi paramétrer différents filtres ou développer un moteur de recherche plus avancé.

Avantages
* Grande flexibilité : Possibilité de défnir un nombre infini de possibilités.

Inconvénients
* Programmation plus lourde : Tous les appels doivent être programmés.
* Cette méthode n’est pas officiellement supportée : La possibilité est laissée aux utilisateurs SityAPI de programmer leur propre client. Cette méthode étant la moins courante et le nombre de clients potentiels illimités, Geolives n’est pas en mesure de fournir de support technique pour l’utilisation de cette méthode.

Contraintes

  • SityAPI est disponible pour tous les clients SityTour en tant que composante de la solution. L’intégration reste cependant à charge du client et Geolives ne propose pas de prestations d’intégration.
  • Ce service est proposé uniquement dans le but de permettre la consultation des randonnées dans un site client. L’utilisation à d’autres fins, telles que l’aspiration de données ou la copie de randonnées peut entrainer la suspension du compte.
  • Le client est prié d’avertir Geolives préalablement à toute montée en charge prévisible (Évènement, publicité, annonce dans les médias, nouveau partenariat) afin d’éventuellement adapter l’infrastructure à absorber le flux de visiteurs.

Instruction d’utilisation de l’API d’intégration de randonnées

Iframe

Le code suivant peut être intégré dans une page. Il sera nécessaire d’y indiquer son nom d’utilisateur afin de filtrer la liste sur ses randonnées.
Les dimensions peuvent être adaptées afin de s’intégrer le mieux possible dans votre page.

Les paramètres de filtrage indiqués dans la présente documentation peuvent être également appliqués à l’URL de l’iframe pour créer des pages thématiques.

Script PHP

Le script suivant permet l’intégration des randonnées dans un site web :

<!--?php <?php $geolives_user = "chevreuse";// DEFINIR ICI LE NOM D'UTILISATEUR $geolives_basepage="http://sitytour.net/testchevreuse/"; // <=== CHANGER ICI =======CHANGER ICI===========CHANGER ICI======CHANGER ICI $geolives_lang ="fr"; // -- PARAMETRES AVANCES------------------------------------- $geolives_Nville = (isset($_GET['Nville']))?$_GET['Nville']:""; $geolives_country=(isset($_GET['country']))?$_GET['country']:""; $geolives_admin1=(isset($_GET['admin1']))?$_GET['admin1']:""; $geolives_admin2=(isset($_GET['admin2']))?$_GET['admin2']:""; $geolives_onlygold=(isset($_GET['onlygold']))?$_GET['onlygold']:""; $geolives_ville=(isset($_GET['ville']))?$_GET['ville']:""; $geolives_category=(isset($_GET['category']))?$_GET['category']:""; // -- NE RIEN MODIFIER SOUS CETTE LIGNE -- $geolives_idrando=(isset($_GET['idrando']))?$_GET['idrando']:""; $geolives_type=(isset($_GET['randotype']))?$_GET['randotype']:"list"; $geolives_user=($geolives_user=="" && isset($_GET['username'])) ? $_GET['username']:$geolives_user; $geolives_maxsize="medium"; // Taille de la fenêtre de détails (medium - large) $geolives_base = (!isset($geolives_basepage) || $geolives_basepage=="")?urlencode($_SERVER['REQUEST_URI']):urlencode($geolives_basepage); $geolives_nosearch=1; $geolives_page = (isset($_GET['page']))?$_GET['page']:""; $geolives_url = "http://www.sitytrail.com/tours/API?inUTF=true&context=inserted&lang=$geolives_lang&username=$geolives_user&type=$geolives_type&id=$geolives_idrando&size=$geolives_maxsize&base=$geolives_base&page=$geolives_page&country=$geolives_country&admin1=$geolives_admin1&admin2=$geolives_admin2&ville=$geolives_ville&category=$geolives_category&search=$geolives_nosearch&onlygold=$geolives_onlygold&Nville=$geolives_Nville"; $statspage = file_get_contents($geolives_url); echo(str_replace(array("\r\n", "\r", "\n"), ' ', $statspage)); ?-->

Description des paramètres

Paramètres de base :
Attribut Rôle Valeur Exemple
$geolives_user Utilisateur cible Nom de l’utilisateur propriétaire des randonnées tartempion
$geolives_basepage Emplacement page cliente Adresse exacte avec paramètres de la page affichant les résultats http://www.example.com/balades.html
$geolives_lang Langue cible fr/nl/en/de fr
Paramètres avancés :

Les paramètres ci-dessous peuvent être définis par le développeur afin de “forcer” le filtrage selon un ou plusieurs critères.

Attribut Rôle Valeur Exemple
$geolives_Nville Filtrage par ville Nom de la localité (Urlencodé) seraing
$geolives_country Filtrage par pays Code pays ([[Liste_des_codes_pays Liste des pays]])
$geolives_admin1 Filtrage par région Code région (Liste sur demande) 10
$geolives_admin2 Filtrage par province/département Code Admin 2(Liste sur demande) 10
$geolives_ville Filtrage par localité Code localité (Liste sur demande) - Dans le cas de plusieurs villes, séparer celles-ci par un point-virgule 10 (OU 10;11;...)
$geolives_onlygold Filtrage randonnées SityTour La définition d’une valeur à ce paramètre enclenche le filtrage des randonnées SityTour true
$geolives_category Filtrage par sport Filtrage par type de sport ([[Liste_des_codes_sport Liste des sports]])
Méthodes de filtrage des paramètres avancés

Filtrage par script:
Le filtrage par script consiste à remplacer la définition des variables dans le script d’intégration par des valeurs “forcées”.
Exemple :
[…]
$geolives_category=3;
[…]

Filtrage par paramètres d’url:
Dans ce cas de figure, le script d’intégration est laissé tel quel et les valeurs de filtrages sont passées en paramètres à la page appelante.
Exemple :
[…]
http://www.example.com/balades.html?category=1
[…]

En savoir plus

L’article Requêtes avancées sur SityAPI présente les options avancées de filtrage

Formats disponibles : PDF HTML TXT