Gedeon API

L'API vous permet d'accéder simplement aux annonces immobilières, liées à votre abonnement.

Elle est accessible en RESTful, à l'adresse http://api.gedeon.im .

API Key

Pour utiliser l'api, il vous faudra une clé, que vous pouvez obtenir nous contactant sur api@gedeon.im.

La clé devra être passée en paramètre de chaque requête, sous le nom key.

Pagination

Important : la pagination est obligatoire. Il est impossible de récupérer plus de 100 resources à la fois.

C'est à dire que si vous ne spécifiez pas de limit, il est fixé par défaut à 100.

Il est donc nécessaire d'effectuer plusieurs requêtes avec l'argument offset, en prenant en compte la valeur total_results en compte.

Il est également conseillé de spécifier explicitement une limit à chaque appel, afin d'éviter tout ambigüité.

REST / JSON

Les requêtes suivent le standard REST, tandis que les réponses sont exclusivement au format JSON.

Ressources

Ads

La ressource ad correspond à une annonce immobilière.

[1] Informations sur le prix :

Ces informations reprennent le prix, et les champs extras, afin de vous aider à l'affichage et respecter la loi ALUR.

Ce champ n'est pas activé par défaut; pour cela il faut que vous passiez le paramètre "priceInfo" en fonction du formatage souhaité :
  priceInfo=html
ou
  priceInfo=text

Contenu :

  • <key> :
    • euros : Prix formaté en euros (avec séparateur de milliers) (String)
    • prefix : Text (court) à afficher avant le prix (le cas échéant)(String)
    • suffix : Text (court) à afficher après le prix (le cas échéant)(String)
    • euros+ : Contient "prefix + euros + suffix" (String)
    • moreinfos : Éléments (concis) possibles à afficher près du prix (Object)
    • alurinfos : Éléments (verbeux) liés à la loi ALUR (Object)

[2] Les informations libres sont sous la forme suivante :

  • <key> :
    • name : Nom de l'information (String)
    • value : Valeur de l'information (Mixed)
    • display : Information destinée à être affichée en l'état (Boolean)
    • category : Nom de la catégorie de l'information (String)

Il est conseillé de ne pas afficher telles quelles les informations où "display" est "false". Elles peuvent cependant être utilisées pour d'autres choses (Pictos, ...).

La liste complète des champs extras est consultable sur cette page.

[3] Les détails des pièces peuvent se représenter sous la forme :

Nom surfacedesc nb
chambre 113
chambre 217 avec dressing
salon 22 parquet
cuisine équipée
wc 2
sdb 1

Ils seront alors fourni par l'API sous la forme (JSON):

{
	"chambre 1" : { "surface" : 13 },
	"chambre 2" : { "surface" : 17, "desc" : "avec dressing" },
	"salon"     : { "surface" : 22, "desc" : "parquet" },
	"cuisine"   : { "desc" : "équipée" },
	"wc"        : { "nb" : 2 },
	"sdb"       : { "nb" : 1 }
}

Note : on ne trouvre pas que des "pièces" dans ce champ, mais aussi d'éventuelles dépendances (cave, garage, ...).

[4] Les photos sont indiquées sous la forme suivante :

Les photos sont sous la forme suivante :

  • url : URL pour accéder à la photo (String)
  • desc Optionnel, rare: Description de la photo (String)

Les photos sont en Jpeg.


Premier cas d'utilisation par défaut : Dans l'URL de la photo, il est possible de remplacer le mot "large" par un nom de format différent, parmi :

    format Image contenue dans Qualité Jpeg Taille moyenne (octets)
    "thumb" 50x50 pixels 50 790
    "medium" 100x100 pixels 65 1900
    "large" 300x300 pixels 75 31000
    "large2" 640x480 pixels 75 37000
    "large3" 800x600 pixels 75 68500

D'autres tailles et formats sont disponibles, merci de nous contacter !

Deuxième cas d'utilisation : Lorsque les photos sont hébergées sur media.studio-net.fr, ces arguments sont disponibles à la fin de l'URL :

    Argument Exemple Description
    Largeur d'image width=X Définit la largeur de l'image à X pixels
    Hauteur d'image height=X Définit la hauteur de l'image à X pixels
    Redimensionnement func=crop Définit le mode de redimensionnement de l'image (cover | fit | bound | crop)
    Recadrage gravity=X Définit la partie de l'image à conserver lors du recadrage : X = [nord | sud][est | ouest] | automatique | X,Y

[5] Les contenus disponibles via URLs dépend fortement des clients/logiciels utilisés.

[6] Les informations énergétiques (DPE et GES) se situent dans les champs libres.

4 champs disponibles :

  • dpe_conso_en: valeur DPE
  • dpe_conso_lettre: classe DPE
  • dpe_ges: valeur GES
  • dpe_ges_lettre: classe GES
  • dpe_date: Date du DPE
  • version_dpe: Version du DPE

Pour chaque annonce, soit la valeur et la classe sont fournies, soit uniquement la classe, si nous ne disposons pas de la valeur. Aucun champ n'est renseigné, si nous ne disposons d'aucune information (ni classe ni valeur).

Pour afficher le graphe, vous pouvez utiliser le composant https://dpe.gedeon.im. Pour ce faire, nous vous proposons une URL unifiée permettant de gérer les DPE effectués pré-juillet 2021 et post-juillet 2021.

  • Sticker DPE & GES: https://dpe.gedeon.im/sticker?dpe={dpe_conso_en}&ges={dpe_ges}&date={dpe_date}
  • Badge DPE: https://dpe.gedeon.im/badge/dpe?dpe={dpe_conso_en}&ges={dpe_ges}&date={dpe_date}
  • Badge GES: https://dpe.gedeon.im/badge/ges?dpe={dpe_conso_en}&ges={dpe_ges}&date={dpe_date}

Si la date du DPE se situe avant le

2021-07-01
, alors seul l'un de ces champs
dpe
ou
ges
est obligatoire. La date est aussi optionnelle mais le graphique sera considéré comme antérieur à la nouvelle norme DPE.

Méthode autorisées

Critères de recherche

Les critères de recherche sont les suivants :

Exemples de listes d'intervalles :

1 1 uniquement
1,3 1, et 3
1-5, 7 de 1 à 5, et 7
-3 de 0 à 3
4- de 4 à ∞

Toutes les bornes sont incluses.

Formatage des résultats

Il vous est possible de rajouter les paramètres suivants, pour modifier les formatage des résultats.

Types de biens

Voici les différentes catégories de biens.

Pour la recherche, elle fonctionne avec le terme en anglais comme en français.

Maison (house)
Appartement (flat)
Garage (garage)
Terrain (terrain)
Local Industriel (industrial)
Bureau (office)
Commerce (shop)
Autre (other)

Agencies

La ressource agency correspond à une agence immobilière.

Format horaires d'ouverture Format simplifié, compatible micro formats.
Exemple:
Mo 08:00-12:00,13:30-17:45;Tu 08:00-12:00,13:30-17:45;We 08:00-12:00;Th 08:00-12:00,13:30-17:45;Fr 08:00-12:00,13:30-17:45
"Simplifié" signifie qu'il n'y aura jamais d'intervalle (Mo-Fr), ni de commentaire, ni d'informations sur les périodes vacances.

Méthode autorisées

Critères de recherche

Les critères de recherche sont les suivants :

Opinions

La ressource opinion correspond à un avis concernant une agence immobilière.

Méthode autorisées

Critères de recherche

Support

Pour toute question, nous sommes à votre disposition sur l'adresse api@gedeon.im.