Référence d’API

Listings API

Une API REST en lecture seule qui fournit l’ensemble complet et à jour des annonces actives en JSON. Elle est conçue pour la synchronisation planifiée : votre plateforme interroge le flux à intervalles réguliers et garde une copie identique à celle d’Osyro.

Demander un accès à l’API Démarrage rapide

Sur cette page

Présentation
Démarrage rapide
Authentification
Endpoints
Lister les annonces
Récupérer une annonce
Synchronisation
L’objet annonce
Exemple d’annonce
Erreurs
Garanties du flux
Assistance

Présentation

URL de base: https://api.osyro.com
Authentification: En-tête X-API-Key
Format: JSON via HTTPS
Horodatage: ISO 8601, UTC

Démarrage rapide

Trois étapes jusqu’à votre première réponse.

1
Obtenez une clé d’API auprès de l’équipe Osyro et stockez-la dans une variable d’environnement, par exemple OSYRO_API_KEY.
2
Appelez GET /listings avec la clé dans l’en-tête X-API-Key.
3
Lisez total_pages dans la réponse et demandez les pages suivantes.

curl "https://api.osyro.com/listings?page=1&page_size=50" \
  -H "X-API-Key: $OSYRO_API_KEY"

200 · Réponse

{
  "page": 1,
  "page_size": 50,
  "total": 120,
  "total_pages": 3,
  "listings": [
    { "referenceNumber": "osy-demo-100231", "...": "full listing object" }
  ]
}

Authentification

Chaque requête doit inclure votre clé d’API dans l’en-tête X-API-Key. Les requêtes sans clé valide sont refusées.

Les clés sont délivrées par l’équipe Osyro et rattachées au compte de votre organisation.

Gardez la clé côté serveur. Ne la livrez jamais dans un navigateur ou une application mobile et ne la versionnez jamais. Si vous pensez qu’elle a fuité, contactez Osyro pour la renouveler.

HTTP

GET /listings HTTP/1.1
Host: api.osyro.com
X-API-Key: {YOUR_API_KEY}
Accept: application/json

Endpoints

Deux endpoints en lecture seule. Tous deux renvoient des objets annonce avec exactement les mêmes champs.

GET/listingsRenvoie les annonces actives, page par page, sous forme d’objets annonce complets.
GET/listings/{referenceNumber}Renvoie un objet annonce par son numéro de référence.

GET/listings

Lister les annonces

Renvoie les annonces actives, page par page, sous forme d’objets annonce complets. Utilisez cet endpoint pour la synchronisation complète comme incrémentale. Les pages commencent à 1 ; continuez jusqu’à avoir lu total_pages.

Paramètres de requête

Paramètre	Type	Défaut	Description
`page`	integer	`1`	Numéro de page, à partir de 1.
`page_size`	integer	`50`	Annonces par page, 200 au maximum. Des pages plus grandes réduisent le nombre de requêtes.
`updated_since`	ISO 8601	`aucun`	Uniquement les annonces modifiées à cet instant ou après (inclusif). Utilisez l’heure de début de votre dernière synchronisation réussie.

Réponse

La réponse de liste enveloppe les objets annonce avec des métadonnées de pagination.

Champ	Type	Description
`page`	integer	La page demandée.
`page_size`	integer	Taille de page utilisée.
`total`	integer	Nombre d’annonces correspondantes, toutes pages confondues.
`total_pages`	integer	Nombre de pages. Demandez les pages 1 à `total_pages`.
`listings`	object[]	Tableau des objets annonce de cette page.

curl "https://api.osyro.com/listings?page=2&page_size=200&updated_since=2026-10-01T00:00:00Z" \
  -H "X-API-Key: $OSYRO_API_KEY"

200 · Réponse

{
  "page": 1,
  "page_size": 50,
  "total": 120,
  "total_pages": 3,
  "listings": [
    { "referenceNumber": "osy-demo-100231", "...": "full listing object" }
  ]
}

GET/listings/{referenceNumber}

Récupérer une annonce

Renvoie un objet annonce par son numéro de référence. Inutile pour la synchronisation, mais pratique pour des vérifications ponctuelles, le support et le débogage d’une annonce.

Paramètre de chemin

Paramètre	Type	Description
`referenceNumber`	string	Le `referenceNumber` de l’annonce.

L’objet annonce →

curl "https://api.osyro.com/listings/osy-demo-100231" \
  -H "X-API-Key: $OSYRO_API_KEY"

Synchronisation

Le flux ne contient que les annonces actives. Votre rôle : garder votre copie identique, en ajoutant les nouveautés, en mettant à jour les changements et en dépubliant ce qui a disparu.

Synchronisation complète

Parcourez /listings sans updated_since : vous obtenez toutes les annonces actives.

Synchronisation incrémentale

Passez l’heure de début de votre dernière synchronisation réussie dans updated_since pour ne récupérer que les changements.

Détecter les changements

Un nouveau referenceNumber est une nouvelle annonce. Un lastUpdated plus récent signifie une modification.

Les annonces vendues, louées ou retirées disparaissent du flux au lieu d’être marquées. Tout referenceNumber absent d’une synchronisation complète doit être dépublié de votre côté.

Recette : synchronisation complète

Lancez une synchronisation complète à la première connexion, puis régulièrement (par exemple chaque nuit) pour détecter les retraits.

# Full sync: fetch every page, then unpublish anything not seen.
page=1
while :; do
  body=$(curl -s "https://api.osyro.com/listings?page=$page&page_size=200" \
    -H "X-API-Key: $OSYRO_API_KEY")
  echo "$body" | jq -c '.listings[]' >> listings.ndjson
  total_pages=$(echo "$body" | jq '.total_pages')
  [ "$page" -ge "$total_pages" ] && break
  page=$((page + 1))
done

Recette : synchronisation incrémentale

Lancez des synchronisations incrémentales fréquentes (par exemple toutes les 15 minutes) pour intégrer rapidement nouveautés et modifications.

# Incremental sync: only listings changed since your last successful run.
curl "https://api.osyro.com/listings?page=1&page_size=200&updated_since=$LAST_SYNC_START" \
  -H "X-API-Key: $OSYRO_API_KEY"

Enregistrez l’heure de début de la synchronisation, pas celle de fin, et utilisez-la comme prochain updated_since. Comme updated_since est inclusif, rien ne passe entre les mailles.
Faites un upsert par referenceNumber : retraiter une annonce est toujours sans risque.
La synchronisation incrémentale ne signale pas les retraits : combinez-la avec une synchronisation complète régulière.
Utilisez page_size=200 pour réduire le nombre de requêtes.

L’objet annonce

Une annonce a la même forme dans les deux endpoints. Les noms de champs sont sensibles à la casse ; les valeurs d’énumération sont des textes exacts comparés sans tenir compte de la casse.

Toujours présents uniquement

Toujours présentSi applicableSi disponible

Identité

Champ	Valeurs et remarques
`referenceNumber`string Toujours présent	Identifiant unique et stable, jamais modifié ni réutilisé. Utilisez-le comme clé primaire.
`lastUpdated`ISO 8601 Toujours présent	Change dès qu’un champ change, y compris le prix et les images.

Classification

Champ	Valeurs et remarques
`category`enum Toujours présent	Catégorie du bien. `Residential` `Commercial`
`purpose`enum Toujours présent	Vente ou location. `For Sale` `For Rent`
`frequency`enum Si applicable	Locations uniquement. Période à laquelle se rapporte le prix. `Monthly` `Weekly` `Daily`
`completionStatus`enum Si disponible	État d’achèvement. `Completed` `Off Plan`
`unitType`string Toujours présent	Type de lot. Liste ouverte : gérez les valeurs inconnues sans erreur. `Apartment` `Villa` `Townhouse` `Office` `Shop` `Warehouse` `Land` `…`

Contenu

Champ	Valeurs et remarques
`title`string Toujours présent	Titre de l’annonce.
`description`string Toujours présent	Description complète. Peut contenir du HTML : à assainir avant affichage.
`images`string[] Toujours présent	URL HTTPS ordonnées ; la première est la couverture. Au moins 1024 px sur le grand côté.

Surface et agencement

Champ	Valeurs et remarques
`unitBuiltupArea`number Toujours présent	Surface construite, dans l’unité unitMeasure.
`unitMeasure`enum Si disponible	sqm par défaut si absent. `sqm` `sqft`
`bedrooms`number \| string Si applicable	Résidentiel uniquement. Studio : 0 ou "Studio".
`bathrooms`number Si disponible	Nombre de salles de bains.
`furnishing`enum Si disponible	Niveau d’ameublement. `Fully furnished` `Semi-furnished` `Unfurnished`
`facilities`string[] Si disponible	Équipements, par ex. Balcony, Shared Pool, Security.

Prix

Champ	Valeurs et remarques
`price`number Toujours présent	En QAR. Prix de vente, ou loyer par frequency.

Localisation

Champ	Valeurs et remarques
`city`string Toujours présent	Par ex. Doha, Lusail, Al Wakrah, selon les noms des grands portails qatariens.
`area`string Toujours présent	Quartier ou tour le plus précis, par ex. Porto Arabia, West Bay.
`latitude`number Toujours présent	Degrés décimaux WGS84.
`longitude`number Toujours présent	Degrés décimaux WGS84.

Conditions de location

Champ	Valeurs et remarques
`rentalPeriod`enum Si disponible	Durée du bail. `Less than 1 year` `Annual contract` `More than 1 year`
`deposit`enum Si disponible	Dépôt de garantie. `1 Month` `2 Months` `Negotiable` `None`
`commission`enum Si disponible	Commission d’agence. `1 Month` `1/2 Month` `Negotiable` `None` `Percentage` `Cash` `Other` `Not applicable`
`freeMonths`enum Si disponible	Mois de loyer offerts. `0` `1` `2` `3` `4`

Caractéristiques

Champ	Valeurs et remarques
`kitchen`enum Si disponible	Type de cuisine. `Closed` `Open` `Fitted` `Unfitted` `Kitchenette` `None`
`parking`enum Si disponible	Type de stationnement. `Covered` `Uncovered` `Underground` `Dedicated - Covered` `Dedicated - Uncovered` `Dedicated - Underground` `On street parking`
`acType`enum Si disponible	Climatisation. `Central` `Split` `Windows` `None`
`kahramaa`boolean Si disponible	Électricité et eau (Kahramaa) incluses dans le loyer.
`internet`boolean Si disponible	Internet inclus dans le loyer.

Agent

Champ	Valeurs et remarques
`agent.name`string Toujours présent	Nom complet.
`agent.phone`string Toujours présent	Format international, +974XXXXXXXX.
`agent.email`string Toujours présent	Adresse e-mail.
`agent.photo`string Si disponible	URL de la photo de profil.

Exemple d’annonce

Une location résidentielle complète, avec des données illustratives.

listing.json

{
  "referenceNumber": "osy-demo-100231",
  "lastUpdated": "2026-09-22T07:47:10Z",
  "category": "Residential",
  "purpose": "For Rent",
  "frequency": "Monthly",
  "rentalPeriod": "Annual contract",
  "deposit": "1 Month",
  "commission": "1 Month",
  "freeMonths": 1,
  "completionStatus": "Completed",
  "unitType": "Apartment",
  "title": "Elegant 1BR Apartment, Porto Arabia",
  "description": "<p>Spacious 1BHK with sea view</p>",
  "unitBuiltupArea": 95,
  "unitMeasure": "sqm",
  "bedrooms": 1,
  "bathrooms": 2,
  "furnishing": "Fully furnished",
  "facilities": ["Balcony", "Shared Pool", "Security"],
  "kitchen": "Fitted",
  "parking": "Covered",
  "acType": "Central",
  "kahramaa": true,
  "internet": true,
  "price": 7500,
  "city": "Doha",
  "area": "Porto Arabia",
  "latitude": 25.3725,
  "longitude": 51.541,
  "images": [
    "https://cdn.example.com/100231/1.jpg",
    "https://cdn.example.com/100231/2.jpg"
  ],
  "agent": {
    "name": "Jane Doe",
    "phone": "+97455500000",
    "email": "jane.doe@example.com",
    "photo": "https://cdn.example.com/agents/1.jpg"
  }
}

Erreurs

Les requêtes en échec renvoient un statut HTTP d’erreur et un corps JSON avec un code applicatif et un message. Fiez-vous à Code ; le message est destiné aux humains et peut changer.

Code	Description	Que faire
`201`	Clé d’API absente ou invalide.	Vérifiez l’en-tête `X-API-Key`. Ne réessayez pas avant correction.
`202`	La clé est valide mais n’a pas accès au flux.	Contactez Osyro pour vérifier votre compte. Ne réessayez pas.
`203`	Erreur serveur temporaire.	Réessayez avec un délai croissant. Contactez Osyro si cela persiste.

4xx / 5xx · Réponse

{
  "Code": 201,
  "Message": "Invalid access token"
}

Réessayer en toute sécurité

Tous les endpoints sont en lecture : réessayer est toujours sûr. Ne réessayez que les erreurs serveur, avec des délais croissants.

Notez le Code et l’heure de la requête lorsque vous contactez le support. N’envoyez jamais votre clé.

# Retry server errors (code 203) with backoff: 1s, 2s, 4s, 8s, 16s
for delay in 1 2 4 8 16; do
  status=$(curl -s -o page.json -w "%{http_code}" \
    "https://api.osyro.com/listings?page=1" -H "X-API-Key: $OSYRO_API_KEY")
  [ "$status" -lt 500 ] && break
  sleep "$delay"
done

Garanties du flux

Une synchronisation complète renvoie toutes les annonces actives, sans omission pour des raisons de performance.
referenceNumber est stable et jamais réutilisé.
lastUpdated change à chaque modification, y compris prix et images.
updated_since est inclusif : à l’instant donné ou après.
Les URL d’images sont publiques et stables en HTTPS ; la première est la couverture.
Les prix sont en QAR ; les loyers sont exprimés par frequency.
Les téléphones des agents suivent le format +974XXXXXXXX.
Tous les horodatages sont en UTC.

Besoin d’une clé ou d’aide ?

Les clés d’API, les questions techniques et l’accompagnement à l’intégration viennent directement de l’équipe Osyro.

Contacter l’équipe Osyro

Listings APIListings API