Développeurs

Afin d'assurer une diffusion maximum des annonces, vous pouvez utiliser les méthodes suivantes pour afficher les annonces sur votre site/blog/forum : flux RSS, fichier CSV, API JSON... Mais également sur votre page Facebook !

Notez que pour protéger les données personnelles des internautes, les noms, prénoms, e-mail, no de téléphone des publicateurs des annonces ne sont pas diffusés.

Vous n'êtes pas autorisé à sauvegarder de manière durable ces annonces, seule leur diffusion est autorisée. Une fois l'annonce supprimée sur le site, veuillez ne plus l'afficher non plus.

Page Facebook

Si vous avez une page Facebook, que ce soit pour une association, une mairie, une communauté... le site peut (avec votre autorisation) publier automatiquement les annonces sur votre page. Vous pouvez décider du type d'annonce qui vous intéresse : les chiens et/ou les chats, les perdus et/ou les trouvés, la/les races, le pays, la région, le/les codes postaux... Pour cela :

En bonus, à chaque fois qu'une annonce est publiée sur votre page, un lien vers votre page est affiché sur le site. Cela vous permettra d'augmenter votre audience !

Flux RSS

Le flux RSS des dernières annonces du pays est disponible à l'adresse suivante :
https://www.chat-perdu.org/fr-dz/rss.xml?cou=dz

Il est possible de filtrer le flux avec les variables (facultatives) suivantes :
isl : "1" pour les chats perdus ou "0" pour les chat trouvés.
ism : "1" pour les males ou "0" pour les femelles.
rac : une race de chat (inspirez-vous de la liste des races pour utiliser la syntaxe exacte).
cou : code du pays (fr, be, ch, lu...).
reg : un code de région. Il faut également indiquer le pays pour utiliser la région.
cps : un ou plusieurs codes postaux séparés par des virgules (max 10). Il faut également indiquer le pays pour utiliser le code postal.
Exemples :
     - les annonces du département 74 en Francehttps://www.chat-perdu.org/fr-dz/rss.xml?cou=fr&reg=74
     - tous les boxers https://www.chat-perdu.org/fr-dz/rss.xml?rac=boxer
     - les chats mâles perdus du canton Suisse de Genève https://www.chat-perdu.org/fr-dz/rss.xml?isl=1&ism=1&cou=ch&reg=ge

Fichier CSV (Excel)

Vous pouvez aussi récupérer la liste des dernières annonces au format CSV à l'adresse ci-dessous :
https://www.chat-perdu.org/items_xls.php

Notez que ce fichier ne présente qu'une liste des dernières annonces. Pour disposer d'une liste complète, veuillez en faire la demande par e-mail.

Il est possible de filtrer le fichier avec les variables (facultatives) suivantes :
isl : "1" pour les chats perdus ou "0" pour les chat trouvés.
ism : "1" pour les males ou "0" pour les femelles.
rac : une race de chat (inspirez-vous de la liste des races pour utiliser la syntaxe exacte).
cou : code du pays (fr, be, ch, lu...).
reg : un code de région.
cps : un ou plusieurs codes postaux séparés par des virgules (max 10).

API JSON

L'utilisation de l'API nécessite une clef personnelle (k) et une clef secrète (secret). Veuillez en faire la demande par e-mail.

Connexion

La connexion à l'API se fait à l'adresse : https://www.chat-perdu.org/api
Vous devez transmettre à l'API le paramètre v qui indique le numéro de version de l'API. A date, il s'agit de la version 2.
Indiquez donc : https://www.chat-perdu.org/api?v=2
Les autres paramètres vont être communiqués à l'API via le paramètre data. Ce paramètre est un tableau de variables au format JSON qui est ensuite encodé en base64.

Commencez par créer un tableau des différentes variables que vous souhaitez communiquer à l'API. Les variables suivantes sont obligatoires :
k : votre clef personnelle de connexion à l'API
datetime : la date et l'heure de la requête au format AAAA-MM-JJ HH:MM:SS
client_v : la version de votre application au format x.y
language : à ce stade "fr" uniquement
country : le code pays qui donnera le contexte de l'application : "fr", "be", "ch"...
client_ip : l'adresse IP du client final utilisateur de l'application
sign : la signature de votre requête. Il s'agit du SHA1 des éléments suivants : datetime k secret (séparés par des espaces)

En plus des variables ci-dessus, vous allez pouvoir ajouter de nouvelles variables pour indiquer à l'API la nature de votre requête.
method : le type de données que vous souhaitez recevoir. Cf ci-dessous.

Récupérer une liste d'annonces

Indiquez la méthode item_selects pour recevoir une liste d'annonces.
Vous pouvez ensuite préciser dans un tableau args les critères suivants pour filtrer les annonces :

limit : le nombre d'annonces à retourner. Maximum 50. Par défaut 30.

page : la page de résultat à afficher par rapport à la limite indiquée ci-dessus.

type : "lost" pour les chats perdus ou "found" pour les chat trouvés.

is_reunited : "true" pour les chats retrouvés.

country : le code du pays (fr, be, ch, lu...). Retrouvez la liste des pays grâce à la méthode local_selects.

region : le code de la région (sous partie d'un pays). Pour la France, c'est le code du département. Cet argument n'a de sens que lorsqu'il est associé à un code pays. Retrouvez la liste des régions grâce à la méthode local_selects.

zip : un code postal. Cet argument n'a de sens que lorsqu'il est associé à un code pays.

lat_min, lat_max, lng_min, lng_max : latitudes (min, max) et longitudes (min, max) encadrant la zone de recherche.

sex : "male" pour les males ou "female" pour les femelles. Il est également possible d'indiquer "male_or_unknown" ou "female_or_unknown" pour récupérer également les annonces pour lesquelles le sexe est inconnu. Pour un chat perdu, le propriétaire connaît le sexe de son chat. Par contre, dans le cas d'un chat trouvé ou juste aperçu, la personne ne sait pas toujours indiquer avec certitude le sexe de l'animal.

race : l'id d'une race. Retrouvez la liste des races grâce à la méthode option_selects.

sizing : l'id d'une taille. Retrouvez la liste des tailles grâce à la méthode option_selects.

fur_size : l'id d'une taille de pelage. Retrouvez la liste des tailles de pelage grâce à la méthode option_selects.

fur_drawing : l'id d'un motif de pelage. Retrouvez la liste des motifs de pelage grâce à la méthode option_selects.

d_found_after : trouvé après une date au format aaaa-mm-jj.

d_lost_before : perdu avant une date au format aaaa-mm-jj.

t_updated : annonces insérées ou modifiées depuis une date/heure au format aaaa-mm-jj hh:mm:ss.

Récupérer une annonce en particulier

Indiquez la méthode item_select pour recevoir une annonce en particulier. Vous devez ensuite préciser l'identifiant de l'annonce dans la variable id

Récupérer la liste des zones géographiques

Indiquez la méthode local_selects pour recevoir la hiérarchie des zones géographiques.

Publier une annonce

Indiquez la méthode item_insert pour publier une annonce et envoyez l'ensemble des données ci-dessous par la méthode POST. Toutes les données sont obligatoires, sauf mention contraire.

type : lost ou found en fonction du type d'annonce

d_lost_found : la date de perte ou de découverte de l'animal au format aaaa-mm-jj.

ref : une référence facultative = un identifiant de l'annonce qui vous est propre (12 caractères max)

street : la rue. Ce n'est pas une donnée obligatoire

zip : le code postal. il doit être conforme au pays indiqué. Par exemple, le code postal 98000 correspond à Monaco et c'est donc le code pays mc qui doit être indiqué. Idem pour les DOM TOM.

city : la ville

country : le code du pays. fr pour la France. Les codes disponibles sont : fr, be, ch, lu, mc et les codes des DOM TOM : gp, mq, gf, re, yt, pm, bl, mf, wf, pf, nc.

geo_lat : latitude

geo_lng : longitude

name : le nom de l'animal. Ce n'est pas une donnée obligatoire pour les animaux trouvés. Il est par contre obligatoire pour les animaux perdus (indiquer "sans nom" si l'animal perdu n'a pas de nom). Le nom ne doit pas contenir les mots ou symboles suivants : tatoué, trouvé, retrouvé, perdu, et, / & ( ) : , + ! ou des chiffres.

sex : male, female ou unknown. Ne peut pas être "unknown" pour un chat perdu.

races : le ou les identifiants des races de l'animal. Ce n'est pas une donnée obligatoire. Il est possible d'indiquer jusqu'à 3 identifants dans un tableau. Les identifiants doivent être différents car un animal ne peut avoir 2 fois la même race.

colors : un ou plusieurs identifiants de couleurs à transmettre dans un tableau.

fur_size : l'identifiant de la taille du pelage.

fur_drawing : l'identifiant du motif de pelage.

is_steril : est-ce que l'animal est stérilisé/castré : true, false ou unknown. Ne peut pas être "unknown" pour un chat perdu.

tatoo : présence d'un tatouage : true, false ou unknown. Ne peut pas être "unknown" pour un chat perdu.

tatoo_detail : si un tatouage est présent (true), quel est il ? Cette donnée n'est pas obligatoire

chip : présence d'une puce : true, false ou unknown. Ne peut pas être "unknown" pour un chat perdu.

chip_detail : si une puce est présente (true), quel est son numéro ? Cette donnée n'est pas obligatoire

description : description de la situation de la perte ou de la découverte de l'animal.

user_name : le prénom et le nom du publicateur de l'annonce.

user_tel : le numéro de téléphone du publicateur de l'annonce. Cette donnée est facultative.

user_email : l'adresse e-mail du publicateur de l'annonce.

partners : est ce que le publicateur accepte que son annonce soit publiée sur les sites partenaires de chat-perdu.org ? true ou false.

fb : est ce que le publicateur accepte que son annonce soit publiée sur Facebook ? true ou false.

tw : est ce que le publicateur accepte que son annonce soit publiée sur Twitter ? true ou false.

nopartners : est ce que le publicateur encourage la publication de son annonce sur des sites non affiliés à chat-perdu.org ? true ou false.

cgu : acceptation des Conditions Générales d'Utilisation du site. true.

images : il est possible d'associer plusieurs photos à une annonce. Elles doivent être transmises dans un tableau "images". Seules les photos de type PNG ou JPEG son acceptées. Par ailleurs, les photos envoyées doivent être carrées et d'un poids inférieur à 2Mo.

En retour de cette méthode, vous recevrez l'identifiant (id) attribué à cette annonce ainsi qu'une clef (key). Cette clef sera à retourner dans les futures requêtes afin de pouvoir modifier ou supprimer l'annonce.


Les identifiants des messages d'erreur sont les suivants : type-missing, type-wrong, d-lost-missing, d-lost-wrong-format, d-lost-wrong-logic, d-found-missing, d-found-wrong-format, d-found-wrong-logic, country-missing, country-wrong, zip-missing, zip-wrong, city-missing, geo-lat-missing, geo-lng-missing, name-missing, name-wrong, sex-missing, sex-wrong, race-wrong, colors-missing, colors-wrong, sizing-missing, sizing-wrong, fur-size-missing, fur-size-wrong, fur-drawing-missing, fur-drawing-wrong, ear-missing, ear-wrong, is-steril-missing, is-steril-wrong, tatoo-missing, tatoo-wrong, chip-missing, chip-wrong, user-name-missing, user-email-missing, user-email-invalid, partners-missing, partners-wrong, fb-missing, fb-wrong, tw-missing, tw-wrong, nopartners-missing, nopartners-wrong, cgu-missing, cgu-wrong, image-wrong, image-failed, image-resize-failed, insert-failed


Récupérer la liste des attributs des annonces

Indiquez la méthode option_selects pour recevoir la liste des attributs d'une annonce (races, tailles, couleurs, pelages...).


Récupérer une liste de commentaires

Indiquez la méthode comment_selects et envoyez les éléments suivants pour recevoir une liste de commentaires. Certains commentaires contiendront l'identifiant de l'utilisateur ayant publié le commentaire. Les commentaires sans cet identifiant sont ceux publiés par les utilisateurs non enregistrés.

item_id : identifiant de l'annonce

Les identifiants des messages d'erreur sont les suivants : item-id-missing


Inscrire un utilisateur

Pour inscrire un nouvel utilisateur, indiquez la méthode user_signup et envoyez les éléments ci-dessous.

user_email : adresse e-mail de l'utilisateur

user_password : mot de passe de l'utilisateur

user_login : login de l'utilisateur. Il doit faire entre 3 et 32 caractères et ne contenir que des caractères minuscules et des chiffres : /^[a-z0-9]{3,32}$/

user_language : le code langue de l'utilisateur. Aujourd'hui, "fr" uniquement

user_country : le code pays de l'utilisateur. Aujourd'hui, "fr", "ch", "be", "lu"... les DOM/TOM... Cf la méthode local_selects

Les identifiants des messages d'erreur sont les suivants : email-missing, login-missing, password-missing, login-invalid, email-invalid, email-already-exists, login-already-exists, signup-failed


Authentifier un utilisateur

Pour vérifier les informations de connexion d'un utilisateur (email, mot de passe) via l'API, indiquez la méthode user_signin et envoyez les éléments ci-dessous. Concrètement, cela n'assure pas une authentification de l'utilisateur, mais cela permet de vérifier via l'API un couple email/mot de passe qui servira par la suite pour la publication de commentaires. La méthode retourne l'identifiant utilisateur.

user_email : adresse e-mail de l'utilisateur

user_password_hash : hash du mot de passe de l'utilisateur, c'est à dire le SHA1 de secret mot de passe de l'utilisateur (séparés par un espace)

Les identifiants des messages d'erreur sont les suivants : email-missing, password-hash-missing, signin-failed, user-locked


Publier un commentaire

Via l'API, seuls les utilisateurs qui disposent d'un compte utilisateur peuvent publier un commentaire (les commentaires anonymes ne sont pas autorisés). Ces utilisateurs disposent donc d'une adresse e-mail et d'un mot de passe.
Lors de la publication du commentaire, en plus du texte du commentaire, l'API doit transmettre l'adresse e-mail et le hash du mot de passe de l'utilisateur.

Indiquez la méthode comment_insert et envoyez les éléments suivants pour publier un commentaire.


item_id : identifiant de l'annonce concernée par le commentaire. Notez que sur certaines annonces, les commentaires ne sont plus possibles et en cas de tentative de publication d'un commentaire, un message d'erreur sera alors retourné.

content : le contenu du commentaire. Il doit s'agir de texte brute. Ce texte ne peut pas contenir de liens.

user_email : adresse e-mail du publicateur du commentaire

user_password_hash : hash du mot de passe du publicateur du commentaire, c'est à dire le SHA1 de secret mot de passe de l'utilisateur (séparés par un espace)

user_language : "fr"

user_country : le code pays de l'utilisateur. Aujourd'hui, "fr", "ch", "be", "lu"... les DOM/TOM... Cf la méthode local_selects

Les identifiants des messages d'erreur sont les suivants : item-id-missing, user-email-missing, user-password-hash-missing, content-missing, item-unknown, comment-publish-locked, signin-failed, user-locked, comment-insert-failed


Erreurs

Les réponses de l'API contiennent toujours un code : 200 (réponse positive), 400 (anomalie : donnée manquante pour la méthode en question le plus souvent), 500 (dysfonctionnement de l'API).