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.

• id : Identifiant unique de l'annonce (Int)
• title : Titre de l'annonce (String)
• mandate : Numéro de mandat de l'annonce (String)
• ref : Référence interne de l'annonce (parfois identique à mandate)(String)
• transaction_type : Type de transaction (String), peut être:
  
  • "Location"
  • "Vente"
  • "Location de Vacances"
  • "Viager"
  • "Programme Neuf"
  Ce champs est destiné à l'affichage, il est renvoyé dans la langue demandée.
• transaction_code : Code de la transaction (String), peut être:
  
  • R pour "Location" (Rent)
  • S pour "Vente" (Sell)
  • H "Location de Vacances" (Holiday)
  • L pour "Viager" (Life annuity sale)
  • P pour "Programme Neuf"
  • O pour "Bien vendu" (sOld)
• nb_rooms : Nombre de pièces (Int)
• text : Texte de l'annonce (String)
• text_en : Texte de l'annonce en anglais (String)
• price : Prix HAI ou Loyer CC (€).(Int)
• price_info : Informations prix.(Object) ¹
• rent_period : Périodicité du loyer (String)
• new : Programme neuf ou construction (Boolean)
• surface : Surface habitable approximative (Int)
• type : Type du bien
  • category : Catégorie du bien (String)
  • name : Sous type (String)
• agency : L'agence qui diffuse cette annonce
  • id : Identifiant unique de l'agence (String)
  • name : Nom de l'agence (String)
  • logo : Logo de l'agence (String)
  • homepage : URL du site de l'agence (String)
• localization : Localisation de l'annonce
  • address : Adresse (String)
  • city : Ville (String)
  • zip_code : Code Postal (String)
  • lng : Longitude (degrés) (Float)
  • lat : Latitude (degrés) (Float)
  • acc : Précision de la géo-localisation (Float)
• contact : Informations de contact
  • name : Nom du contact (String)
  • mail : Email du contact (String)
  • phone : Téléphone du contact (String)
• extras : Informations libres (Object)²⁶
• rooms_details : Détails des pièces (Object)³
• photos : Photos (Array of Objects)⁴
• virtualvisit : Url (type http(s)://...) de la visite virtuelle (string) ⁵
  

{
	"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 }
}

2021-07-01

dpe

ges

Méthode autorisées

• GET ads renvoie une liste d'annonce suivant des critères de recherche spécifiés en paramètre.
• GET ads/id renvoie les détails de l'annonce référencée par son identifiant id.

Critères de recherche

Les critères de recherche sont les suivants :

• lang code de la langue dans laquelle seront retournées les annonces
  codes supportés : fr_FR, en_US, de_DE (String)
• transaction Types de transaction (String)

  "sell"	pour les ventes,
  "rent"	pour les locations,
  "holidays"	pour les locations de vacances,
  "sold"	pour les biens vendus
  "viager" (ou "l")	pour les viager (Life annuity sale)
  "program":	pour les Programmes neufs

  Si rien n'est précisé, sont renvoyés tous les types de transactions, sauf les biens vendus qui doivent être explicitement demandés.
  Exemples :

  transaction=	retourne tout sauf les biens vendus
  transaction=sell	retourne les biens en vente
  transaction=sell,rent	retourne ventes et locations
  transaction=sold	retourne les biens vendus uniquement
  transaction=sell,sold	retourne les biens à vendre et les biens vendus
  transaction=sell,viager	retourne les biens à vendre et bien en viager
  transaction=sell,program	retourne les biens à vendre et les programmes neufs

• exclude_transactions liste des transactions à exclure séparées par une virgule
  exemple : exclude_transactions = holidays,rent(String)
• type Type(s) de bien, séparés par des virgules. (Voir liste) (String)
• localization Critères de localisation : ville ou code postal ou département, séparés par des virgules (String)
• extends Extension de recherche, en mètres. Exemple, 3000 pour rechecher 3km aux alentours de localization (Int)
• bbox BoundingBox géographique, au format "lng1,lat1,lng2,lat2" où lng1/lat1 représente le coin Nord-Ouest et lng2/lat2 le coin Sud-Est, en degrés. (String)
• min_price Prix minimum (Int)
• max_price Prix maximum (Int)
• min_surface Surface minimum (Int)
• max_surface Surface maximum (Int)
• rooms Nb. de pièces, plusieurs valeurs possibles séparés par des virgules. La valeur "5" correspond à "5 ou plus". Exemple : "3,4,5". (String)
• agency Identifiant d'une agence (String)
• max_days_old Ancienneté maximum de l'annonce, en jours (Int)
• ll_prec_min Précision minimum de la géolocalisation de l'annonce (Int)
• favorite Uniquement les annonces coup de coeur (Boolean)
• is_new Uniquement annonces concernant le neuf (Boolean)
• is_old Uniquement annonces concernant l'ancien (Boolean)
• nb_photos_min Nombre de photos minimum (Int)
• sleeps Capacité d'accueil du bien. Format : Liste d'intervalles (String)
• bedrooms Nombre de chambres du bien. Format : Liste d'intervalles (String)
• champs de recherche spécifiques viager :
  • monthly_annuity Rente. Formats acceptés : "-500", "200-800", "800-", "0".(String)
    Si 0 est compris dans la sélection (0-500 ou 0), alors les biens sans information de rente seront aussi ramenés.
  • occupied(Bool)
    1 => Uniquement les logements occupés.
    0 => Les logements non marqués comme occupés.
  • nb_persons Nombres de personnes sur lequel porte le viager : "1", "1,2", "2", "0". (String)
    0 => pas d'information sur le nombre de personnes
  • forward_sale Vente à terme (Bool)
    1 => Vente à termes
    0 => Biens non marqués comme étant une vente à terme.
  • forward_duration Terme en nombre d'années : "-10", "10-20". (String)
    Si 0 est compris dans la sélection (0-10 ou 0), alors les biens sans information sur le nombre d'années seront aussi ramenés.
  Exemples de requête :
  • tous les viagers : transaction=L
  • viagers hormis les ventes à termes : transaction=L&forward_sale=0
  • viagers occupés : transaction=L&occupied=1
  • viagers libres : transaction=L&occupied=0
  • ventes à terme: transaction=L&forward_sale=1
  • viagers sans rente: transaction=L&monthly_annuity=0
• sort Tri des annonces, sous la forme "key1 order, key2 order". Exemple : "surface asc, price desc" (String)
• offset Offset des résultats (pour pagination des résultats) (Int)
• limit Limite du nombre de résultats (pour pagination des résultats) (Int)

Formatage des résultats

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

• fields Permet d'obtenir une liste d'annonce minimaliste, en n'affichant que les données spécifiées. (String)
  Champs possibles (séparés par des virgules):
  • ll : demande la latitude (lat, float), la longitude (lng, float), la précision (acc, float)
  • type : demande le type de bien (type, string)
  • transaction : demande le type de transaction (transaction, char) : 'r' pour location, 's' pour vente, 'h' pour location de vacances, 'l' pour viager
  • price : demande le prix (price, int)
  • surface : demande la surface (price, int)
  • rooms : demande le nb. de pièces (rooms, int)
  • address : demande l'adresse du bien (si affichable) (address, string)
  • zip_code : demande le code postal (zip_code, string)
  • city : demande la ville (city, string)
  Exemple : fields=ll,type,transaction
  (pour n'avoir que la latitude/longitude, le type et la transaction)
• priceInfo Permet d'obtenir des informations pré-formatées concernant le prix. (Object)
  Vous devez préciser le format dans lequel vous souhaitez obtenir ces informations :

  text	Texte simple
  html	Texte HTML Produit un text avec de nombreuses classes CSS et des espaces insécables (aucun style n'est appliqué).

  Exemple : priceInfo=html
  Retrouvez le détail de ces informations prix ici.
• tf Permet de formater le texte de l'annonce. (String)
  Par défaut, le texte de l'annonce est brut de forme, en mode texte (pas de balises HTML).
  Voici différentes options et leurs effets (séparés par des virgules):

  strip-urls	Enlève les liens (URLs) présents dans le texte
  strip-mails	Enlève les emails présents dans le texte
  strip-phones	Enlève les num. de téléphone présents dans le texte
  strip-cr	Enlève les sauts de lignes présents dans le texte
  clean-phones	Reformatte les numéros de téléphone
  clean-cr	Évite les sauts de ligne multiples, convertit tous les sauts de ligne en \n
  clean-spaces	Évite les espces multiples
  clean-punctuation	Réécrit la ponctuation
  anchor-urls	Entoure les liens (URLs) présents dans une ancre type <a href="..." (avec nofollow). Seulement if html est activé.
  anchor-mails	Entoure les adresses email présentes dans une ancre type <a href="mailto:..." Seulement if html est activé.
  anchor	Raccourci pour activer anchor-urls et anchor-mails
  recase	Reformatte la casse du texte, seulement si le texte original contient trop de majuscules (> 30%)
  html	Renvoie le texte en HTML : les sauts de ligne sont des <br/>, etc.

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.

Agencies

La ressource agency correspond à une agence immobilière.

• id : Identifiant unique de l'agence (String)
• name : Nom de l'agence (String)
• homepage : URL du site web de l'agence (String)
• logo : URL du logo de l'agence
• localization : Localisation de l'agence
  • address : Adresse (String)
  • city : Ville (String)
  • zip_code : Code Postal (String)
  • lng : Longitude (degrés) (Float)
  • lat : Latitude (degrés) (Float)
  • acc : Précision de la géo-localisation (Float)
• contact : Informations de contact
  • emails : Emails de l'agence (Array of Strings)
  • phone : Téléphone du contact (String)
• photo : URL de la photo (vitrine) de l'agence (si disponible, null sinon)
• description : Description (texte publicitaire de l'agence, champ libre). Sauts de ligne possibles ("\n")
• opening_hours : Horaires d'ouvertures de l'agence (format)
• legal : Informations légales de l'agence.
  • raison_sociale : Raison sociale (String)
  • forme_juridique : Forme juridique (String)
  • adresse_societe : Adresse société (String)
  • no_carte_pro : Numéro de carte professionnelle (String)
  • prefecture : Préfecture (String) (Préfecture où a été établie la carte pro.)
  • rcs : RCS (String)
  • garantie_etablissement : Garantie établissement (String)
  • garantie_montant : Garantie montant (String)
  • rcp_nom : RCP nom (String)
  • rcp_montant : RCP montant (String)
  • honoraires : Honoraires (String) (Texte libre (HTML))
  • infos : Informations complémentaires (String) (Texte libre (HTML))

Méthode autorisées

• GET agencies renvoie une liste d'agence suivant des critères de recherche spécifiés en paramètre.
• GET agencies/id renvoie les détails de l'agence référencée par son identifiant id.

Critères de recherche

Les critères de recherche sont les suivants :

• localization Critères de localisation : ville ou code postal ou département, séparés par des virgules (String)
• keyword Nom des agences, séparés par des virgules. Exemple : "Mallemort,A2MG"(String)
• sort Tri des annonces, sous la forme "key1 order, key2 order". Exemple : "zipcode asc" (String)
• offset Offset des résultats (pour pagination des résultats) (Int)
• limit Limite du nombre de résultats (pour pagination des résultats) (Int)