API Zagaz
Authentification
Il est nécessaire de fournir à chaque requête sur l'API une clé application_key (clé de l'application, différente de l'api_key de l'utilisateur). Cette clé doit être demandée à zagaz.com.
La clé peut être révoquée à tout moment en cas de constation d'une utilisation frauduleuse du site (tentative de récupération complète de l'annuaire).
Coordonnées géodésiques
Les latitudes et longitudes sont exprimées en degré décimal (et non en degré, minute, seconde).
Ainsi, les coordonnées de Notre-Dame de Paris sont exprimées comme suit :
- Latitude : 48.853204
- Longitude : 2.349388
Clé API
Chaque utilisateur doit récupérer sa clé (api_key) nécessaire pour accéder à toutes les informations.
Cette clé est récupérée dans son espace membre sur : https://www.zagaz.com/membre/key.php
Cette clé peut aussi être récupérée via le login/mot de passe de l'utilisateur via la fonction de l'API get-key.php
Codes carburants
Les codes carburants sont les suivants :
| Code utilisé par l'API | Libellé court | Libellé long |
|---|---|---|
| 7 | e10 | SP95 / E10 |
| 3 | s98 | Sans plomb 98 |
| 2 | s95 | Sans plomb 95 |
| 6 | e85 | E85 |
| 5 | gazplus | Gasoil amélioré |
| 1 | gaz | Gasoil |
| 4 | gpl | GPL |
Format de sortie
Par défaut, les sorties se font au format XML. Si on ajoute le paramètre output=json, les sorties se feront alors au format JSON.
Le XML utilise le format ISO-8859-1, le format JSON utilise son propre format (traditionnellement traduit en UTF-8)
Version de l'API
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) |
Exemple de résultat :
https://api2.zagaz.com/version.php?application_key=VOTRE_APPLICATION_KEY
Récuperer la clé unique de l'utilisateur
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| login | oui | ||
| password | oui |
Exemple de résultat :
https://api2.zagaz.com/get-key.php?login=xxx&password=yyy&application_key=VOTRE_APPLICATION_KEY
Listes des stations
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| longitude | oui | ||
| latitude | oui | ||
| carburant | non | Sert au classement par fraicheur de prix et ou distance | |
| rayon | non | 20 | Nombre de km autour du point pour chercher des stations. 20km est le plus grand rayon de recherche |
| limit | non | 30 | Nombre maximum de station récuperer. 30 est le maximum. |
| sort_type | non | 1 | 1: tri par fraicheur du prix, 2: tri par distance (experimental) |
Exemple de résultat :
Détail d'une station
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| id_s | oui | Identifiant de la station retourné par un autre list-station.php ou favoris.php |
Exemple de résultat :
https://api2.zagaz.com/info-station.php?id_s=1&application_key=VOTRE_APPLICATION_KEY
Détail d'un utilisateur
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| id_u | non | l'id_u de l'utilisateur identifié par son api_key | Identifiant de l'utilisateur (récuperé dans info-station) |
Exemple de résultat :
https://api2.zagaz.com/utilisateur-info.php?id_u=1&application_key=VOTRE_APPLICATION_KEY
Prix moyen des carburants et prix du pétrole
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) |
Exemple de résultat :
https://api2.zagaz.com/prix-moyen.php?application_key=VOTRE_APPLICATION_KEY
Inscription d'un utilisateur
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| pseudo | oui | ||
| pwd | oui | Mot de passe | |
| pwd2 | oui | Confirmation du mot de passe | |
| oui | |||
| contrat | oui | Condition d'utilisation de zagaz (http://www.zagaz.com/charte.php), doit être mis à 'on' |
Exemple de résultat :
https://api2.zagaz.com/inscription.php?...&application_key=VOTRE_APPLICATION_KEY
Liste des dossiers de favoris de l'utilisateur
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui |
Exemple de résultat :
https://api2.zagaz.com/dossier.php?api_key=template_milieu&application_key=VOTRE_APPLICATION_KEY
Ajouter un dossier de favoris
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| nom | oui | Le nom du dossier | |
| commentaire | oui |
Exemple de résultat :
Supprimer un dossier (à condition qu'il ne contienne plus de favoris)
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| id_d | non | L'identifiant du dossier à supprimer |
Exemple de résultat :
Editer les propriétés d'un dossier de favoris
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| id_d | non | L'identifiant du dossier à modifier | |
| nom | oui | Le nom du dossier | |
| commentaire | oui |
Exemple de résultat :
Liste tous les favoris
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui |
Exemple de résultat :
https://api2.zagaz.com/favoris-all.php?api_key=template_milieu&application_key=VOTRE_APPLICATION_KEY
Favoris de l'utilisateur
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| carburant | oui | Sert au classement par fraicheur de prix et ou distance | |
| id_d | non | L'identifiant du dossier à lister | |
| limit | non | 30 | Nombre maximum de station récuperer. 30 est le maximum. |
| offset | non | 0 | Afficher les favoris à partir de cette position dans l'ordre de favoris |
Exemple de résultat :
Ajouter un favoris
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| id_s | oui | Identifiant de la station | |
| id_d | oui | 0 | Identifiant du dossier de l'utilisateur (voir la fonction dossier) |
Exemple de résultat :
Supprimer un favoris
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| id_s | oui | Identifiant de la station retourné par favoris.php |
Exemple de résultat :
Mise à jour des prix
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| carburant | oui | ||
| id_s | oui | Identifiant de la station retourné par un autre list-station.php ou favoris.php | |
| prix | oui | Prix du carburant exemple : 1.387 | |
| no_change | non | Si présent et différent de chaine_vide, indique que le prix n'a pas été modifié |
Exemple de résultat :
Mise à jour de plusieurs prix
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| api_key | oui | ||
| id_s | oui | Identifiant de la station retourné par un autre list-station.php ou favoris.php | |
| -identifiant carburant- | non | Prix du carburant, l'identifiant est parmi : 's98','s95','e10','gazplus','gaz','e85' ou 'gpl' | |
| ok*** | non | *** est l'identifiant du carburant. Indique de le prix de ce carburant n'a pas changé |
Exemple de résultat :
Chercher l'identifiant (id_div) d'une ville ou d'un code postal
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| recherche | oui | Chaîne contenant le nom d'une ville ou d'un code postal |
Exemple de résultat :
https://api2.zagaz.com/recherche.php?recherche=01000&application_key=VOTRE_APPLICATION_KEY
Liste les stations dans une ville
| Nom du paramètre | Obligatoire | Valeur par défaut | Commentaire |
|---|---|---|---|
| application_key | oui | Clé de l'application (voir Authentification) | |
| id_div | oui | Identifiant de la ville retourné par la fonction recherche |
Exemple de résultat :
https://api2.zagaz.com/list-station-ville.php?id_div=10050&application_key=VOTRE_APPLICATION_KEY
Notes de mise à jour
Version 1.15
- Améliration de la fonction de recherche
Version 1.14
- Ajout de la fonction recherche
- Ajout de la fonction list-station-ville
Version 1.13
- utilisateur-info : si l'id_u n'est pas fourni, alors on utilise par défaut l'id_u correspondant à l'api_key passée
Version 1.12
- utilisateur-info : ajout de la date d'inscription, d'un lien vers l'avatar, du nombre de prix mise à jour
Version 1.11
- Ajout du prix et des informations de mise à jour des carburants pour les scripts list-station, favoris et favoris-all
Version 1.9
- info-station.php : Ajout de last_id_u,last_maj,last_pseudo dans les propriétés d'une station (pour indiqué qui et quand un utilisateur à mis à jour la station en dernier)
- list-station.php : Ajout de la distance à vol d'oiseau en km (experimental)
- prix-moyen.php : Création de cette fonction qui renvoie le prix moyen des carburants en temps réel et le prix du pétrole.
Version 1.8
- La date de dernière connexion de l'utilisateur est mise à jour sur les fonctions nécessitant une api_key d'utilisateur
- Ajout des fonctions de gestion de favoris : favoris-add et favoris-delete
- Ajout des fonctions de gestion de dossier : dossier-add, dossier-delete et dossier-edit