Skip to main content
Retrieve advert by url
GET /v2/protected/adverts/url?url=… retrouve une annonce à partir de l’URL de sa page sur un portail. Si l’annonce est déjà indexée chez Fluximmo, elle est renvoyée directement. Sinon elle est collectée à la demande, et la requête attend son indexation. Le paramètre url est obligatoire et doit être une url http(s) valide pointant vers une annonce, par exemple https://www.leboncoin.fr/ad/ventes_immobilieres/3246347062. Le contrat exact est documenté plus bas par le bloc OpenAPI (GET /v2/protected/adverts/url).
La requête peut bloquer jusqu’à ~45 secondes avant de répondre, le temps de collecter puis d’indexer l’annonce. Réglez le timeout de votre client HTTP au-dessus de 45 s : la valeur par défaut de la plupart des librairies est plus basse et coupera la requête avant la réponse.
1 crédit est facturé uniquement quand un document est renvoyé (200). Les réponses 202 (indexation en cours) et 422 (rejetée par l’ingestion) ne sont pas facturées.

Les trois issues possibles

  • 200 — l’annonce est disponible. Le corps est l’objet advert, enveloppé : { "data": { … } }. 1 crédit.
  • 202 — collectée, pas encore indexée. Réessayez la même url après retry_after_s secondes. Ce délai est dans le corps ; il n’y a pas d’en-tête HTTP Retry-After.
  • 422 — collectée mais rejetée par l’ingestion (données incohérentes ou manquantes, hors périmètre). Cette annonce ne deviendra jamais disponible : ne réessayez pas.
Ces deux corps sont enveloppés dans data (ce sont des issues métier, pas des erreurs) et portent un champ status lisible par une machine, ainsi que website_ref pour corréler un retry ultérieur. Ne traitez pas website_ref comme garanti : il peut valoir null lorsque l’annonce n’a pas de référence canonique.
Aucune déduplication côté serveur. Deux appels concurrents sur la même url déclenchent deux collectes — et deux crédits si les deux répondent 200. Sérialisez ou dédupliquez vos appels sur une même url.

Cas d’usage

  • Import d’une annonce repérée à la main — un utilisateur colle l’url d’une annonce, vous la rapatriez dans votre base.
  • Enrichissement d’un lien existant — retrouver le flx_id Fluximmo derrière une url portail déjà stockée chez vous.
  • Vérification ponctuelle — obtenir la fiche complète (prix, surface, vendeur) d’une annonce vue sur un portail.

Exemples

1 — Récupérer une annonce par son url

Notez le --max-time 60, supérieur aux ~45 s d’attente maximale.

2 — Gérer le 202 en réessayant après retry_after_s

202 et 422 se distinguent par le code HTTP : on réessaie le premier, jamais le second.

Erreurs

Les erreurs, elles, ne sont pas enveloppées dans data mais dans { "error": { "message", "code" } }.
  • 404 — portail non couvert, url invalide, ou url ne désignant pas une annonce unique (page de recherche, url tronquée).
  • 422 (validation, code 10002) — paramètre url absent, vide ou mal formé. Les trois cas renvoient le même message, "Url query parameter must be a valid http(s) url" ; branchez tout de même sur le code 10002 plutôt que sur le libellé. À ne pas confondre avec le 422 de rejet d’ingestion ci-dessus, qui est un succès métier enveloppé dans data et porte un status.
Détail des codes : Codes d’erreur.

Liens utiles

Clé test gratuite — 1 semaine

Créez un compte sur my.fluximmo.io pour récupérer une clé API test gratuite (1 semaine, accès limité). Aucun paiement requis.

Authorizations

x-api-key
string
header
required

Query Parameters

url
string
required

Url of an ad to get the associated advert

Response

data
object