Documentation
Contact
Référence API

Migrer de la v3.2 vers la v3.3

La version 3.3 de l'API MLS CONNECT est servie sous le préfixe /api/v3.3/. Les préfixes /api/v3/, /api/v3.1/ et /api/v3.2/ continuent de servir les versions 3.0, 3.1 et 3.2, sans aucun changement de forme. Vous migrez donc quand vous le décidez : rien ne change pour vous tant que vous n'avez pas modifié vos URLs.
La 3.3 ne retire ni ne renomme aucun champ. Elle ajoute des valeurs à deux vocabulaires déjà servis, un sous-type de bien et neuf aménagements, de nouvelles clés, et six filtres à la recherche de biens, dont un aussi à la recherche d'agences. Les uns comme les autres n'apparaissent que sous le nouveau préfixe : une version publiée ne change plus de forme, et un client qui ne connaît que la 3.2 pourrait mal les traiter. La description complète de chaque route et de chaque champ est dans la documentation de référence, qui décrit la version 3.3.

Ce qui change

Champ 3.0 à 3.2 3.3
property_subtype.slug d'un loft (recherche) studio loft
property_type.sub_type.slug d'un loft (détail) studio loft
amenities sans les neuf valeurs ci-dessous avec ces neuf valeurs
Nouvelles clés, ci-dessous absentes servies
Filtres country_iso, shapes et leurs ! ignorés appliqués
Filtres agency_network et agency_network! ignorés appliqués

Le sous-type loft

Les lofts sont un sous-type d'appartement à part entière : loft. Jusqu'en 3.2, ils sont servis sous le sous-type studio, avec ses libellés.
// v3.2
"property_subtype": {"slug": "studio", "fr": "Studio", "en": "Studio", …}

// v3.3
"property_subtype": {"slug": "loft", "fr": "Loft", "en": "Loft", …}
En recherche, le filtre suit la version appelée : sous /api/v3.2/, property_subtype=studio ramène aussi les lofts, comme property_subtype!=studio les exclut. Sous /api/v3.3/, studio ne désigne plus que les studios.
À faire : ajouter loft à votre table des sous-types. Si vous filtrez sur studio pour obtenir aussi les lofts, filtrez sur studio,loft.

Neuf aménagements

amenities reçoit neuf nouvelles valeurs :
Valeur Sens
prestige Bien marqué Prestige
pets_accepted Animaux acceptés, avec ou sans conditions, ou au moins une espèce
pets_cats_allowed Chats acceptés
pets_dogs_allowed Chiens acceptés
senior_residence Résidence pour aînés
furnished Meublé
any_parking Au moins un stationnement, garage compris
outdoor_storage Rangement extérieur
storage Un rangement, quel qu'il soit : cave, cellier ou rangement extérieur
parking garde son sens : il exclut le garage, qui a son propre aménagement garage. Le filtre amenity combinant ses valeurs en « et », c'est any_parking qui répond à « un stationnement, quel qu'il soit ».
Le filtre amenity accepte ces valeurs sous tous les préfixes. Seule leur présence dans les réponses dépend de la version.
À faire : accepter ces valeurs dans votre traitement de amenities, ou ignorer celles que vous ne connaissez pas.

Nouvelles clés

Ces clés ne sont servies que sous /api/v3.3/ : sous un préfixe antérieur, elles sont absentes des réponses. Toutes, sauf missing_from_feed_at, s'écrivent en revanche en création et en mise à jour sous tous les préfixes, et les filtres de recherche qui les accompagnent sont acceptés partout.
  • prestige et lifestyles : le drapeau Prestige du bien et ses lifestyles. Le détail sert les preuves de chaque lifestyle, la recherche seulement leur type et leur position. La recherche ne porte pas la clé prestige : un bien Prestige y porte l'aménagement prestige, et lifestyles y est absent quand le bien n'en a aucun. Ils s'écrivent sur un board où le portail Prestige MLS est actif, ailleurs prestige: true et des lifestyles sont refusés ; ils se filtrent avec lifestyle et lifestyle!.
  • inclusions et exclusions : ce qui est inclus avec le bien et ce qui en est exclu, une clé par locale.
  • Dans general de la fiche : outdoor_storage, pets_allowed, pets_cats_allowed, pets_dogs_allowed, senior_residence et senior_autonomy. Chaque résultat de recherche porte les mêmes champs à sa racine, plus handicapped_access, cellar et parking_outside.
  • missing_from_feed_at, à la racine de la fiche et de chaque résultat de recherche : la date à laquelle la source d'import a cessé d'envoyer le bien, null tant qu'elle l'envoie. Elle s'efface quand le bien revient dans le flux ; elle ne s'écrit pas, et une création ou une mise à jour par l'API l'efface aussi. Un bien en vente ou en location qui sort du flux passe en même temps en retrait de mandat. Un bien vendu ou loué garde son statut, et ne reçoit cette date que d'une source qui garde ses ventes dans son flux. Elle se filtre avec les suffixes _gt, _gte, _lt et _lte, et se trie avec sort=missing_from_feed_at.
  • agency_network (slug, name), sur l'agence du bien et sur chaque co-inscripteur, ainsi que dans la recherche et la fiche d'agence : le réseau d'agences (bannière) de l'agence, null si elle n'en a pas. Son slug est la valeur du filtre agency_network.
  • featured, à la racine de la fiche et de chaque résultat de recherche : le drapeau coup de cœur du bien. Il n'existe que sur un board où l'option coup de cœur est activée : ailleurs, il vaut toujours false, y compris sur un bien resté marqué après la désactivation de l'option, et un true envoyé est refusé en 422.
pets_allowed vaut yes, no ou conditional. null signifie que la source ne s'est pas prononcée : ce n'est pas un refus. senior_autonomy vaut autonomous, semi_autonomous ou non_autonomous.
À faire : accepter ces clés, ou ignorer celles que vous ne connaissez pas.

Deux filtres de recherche : country_iso et shapes

country_iso filtre sur le code pays ISO 3166-1 alpha-2 (fr, be, ca…), sans distinction de casse. Le filtre country, lui, attend le slug du pays (france, belgique).
shapes cherche dans une union de zones : des cercles et des polygones séparés par ;, chacun préfixé par son type. Un bien est retenu s'il tombe dans au moins une zone.
shapes=circle:7.272547,43.71769,500m;polygon:7.472159,43.770355,7.471648,43.756619,7.494524,43.755913
Une liste mal formée est refusée en 400. Le format complet est dans la documentation de référence.
country_iso! et shapes! excluent les biens correspondants.

Le filtre agency_network

agency_network ne retient que les biens des agences d'un réseau (bannière), co-inscriptions comprises : agency_network=ROYLEP,PRD, sans distinction de casse. agency_network! exclut les biens de ces réseaux. La recherche d'agences accepte aussi agency_network.
Sous un préfixe antérieur, ces six filtres sont ignorés : la recherche répond comme s'ils n'avaient pas été envoyés.
À faire : ne pas envoyer ces filtres avant d'avoir basculé sur /api/v3.3/, sous peine de recevoir le stock non filtré.

Marche à suivre

  1. Mettre à jour vos référentiels : le sous-type loft, les neuf aménagements et les nouvelles clés.
  2. Revoir vos filtres sur studio, s'il y en a, et n'utiliser country_iso, shapes et agency_network qu'une fois sur le nouveau préfixe.
  3. Tester sur /api/v3.3/ avec vos clés habituelles. Les mêmes clés apiKey et apiToken servent tous les préfixes, sur les mêmes boards.
  4. Contrôler l'en-tête X-Api-Version de vos réponses réussies : il vaut 3.3 sur le nouveau préfixe. Les réponses d'erreur ne le portent pas.
  5. Basculer le préfixe dans votre configuration. Aucune autre modification d'URL n'est nécessaire : les routes sont identiques.
# avant
GET https://app.mls-connect.com/fr/api/v3.2/properties/search?mls_board=xxx

# après
GET https://app.mls-connect.com/fr/api/v3.3/properties/search?mls_board=xxx
Si vous êtes sur un préfixe plus ancien, passez directement à la 3.3 en appliquant aussi les changements décrits dans Migrer de la v3 vers la v3.1 et Migrer de la v3.1 vers la v3.2.

Ce qui ne change pas

  • La forme des réponses : aucun champ n'est retiré, renommé ni retypé
  • Les routes et leurs paramètres
  • Le sens des filtres existants, en dehors de property_subtype sur studio. Les filtres lifestyle, lifestyle! et missing_from_feed_at_*, et le tri sort=missing_from_feed_at, s'y ajoutent sous tous les préfixes ; country_iso, shapes, agency_network et leurs ! sous /api/v3.3/ seulement
  • L'authentification par apiKey et apiToken, et les droits par board
  • La pagination et les curseurs
  • Les codes HTTP des erreurs, tels que la 3.2 les a fixés
  • L'écriture d'un sous-type : studio désigne un studio sous tous les préfixes, et loft s'écrit sous tous les préfixes