API Reference

Base URL: https://locareo.com

L'API Locareo est une API REST retournant du JSON. Toutes les réponses suivent le format :

{
  "data": { ... },         // réponse principale
  "meta": { ... },         // métadonnées (pagination, liens)
  "timestamp": "ISO 8601"  // horodatage de la réponse
}

Authentification

Toutes les routes /api/v1/* et /api/gbca/* nécessitent une clé API. Obtenez la vôtre dans votre espace hôte.

Header (recommandé)

Authorization: Bearer lk_xxxxxxxx.xxxxxxxxx

Query param

GET /api/v1/properties?api_key=lk_xxxxxxxx.xxxxxxxxx

⚠️ Ne jamais exposer votre clé API dans du code client ou des repos publics.

Format GBCA 1.0

Le GroupeB Channel Archive (GBCA) est un format JSON ouvert pour les listings STR. Extension : .groupeb.ca

gbcastring

requisVersion du format. Actuellement "1.0".

generatedISO 8601

requisHorodatage de génération du fichier.

sourceenum

requisSource de l'annonce: airbnb, vrbo, kijiji, booking.com, locareo, lodgify, guesty, hostaway, beds24, manual, other.

sourceUrlstring

optionnelURL de l'annonce d'origine.

propertyobject

requisDonnées complètes de l'hébergement (voir ci-dessous).

hostobject

optionnelInformations sur l'hôte (optionnel).

metaobject

requisMétadonnées: version, checksum SHA-256, signature HMAC.

Propriétés

GET/api/v1/propertiesscope: properties:read

Liste les hébergements actifs. Supporte filtres et pagination.

Paramètres query :

city — filtrer par ville

limit — max 200, défaut 50

offset — pagination

GET/api/v1/properties/{id}scope: properties:read

Détails d'un hébergement. Accepte l'ID interne ou le slug URL.

Disponibilités

GET/api/v1/availabilityscope: availability:read

propertyId — requis

checkIn — YYYY-MM-DD (optionnel)

checkOut — YYYY-MM-DD (optionnel)

{
  "data": {
    "propertyId": "abc123",
    "available": true,
    "checkIn": "2026-07-01",
    "checkOut": "2026-07-05",
    "blockedRanges": [
      { "from": "2026-07-10", "to": "2026-07-15" }
    ],
    "icalFeed": "https://locareo.com/api/ical/abc123.ics"
  }
}

GBCA API

GET/api/gbca/generate?propertyId=xxxscope: gbca:export

Exporte un hébergement au format GBCA. Retourne le fichier .groupeb.ca en téléchargement.

POST/api/gbca/importscope: gbca:import

Importe un fichier GBCA et crée un hébergement.

Body: contenu JSON du fichier .groupeb.ca

POST/api/gbca/from-urlscope: gbca:import

Convertit une URL de listing vers le format GBCA.

// Body
{ "url": "https://www.airbnb.ca/rooms/12345" }

// Add ?format=gbca to download the .groupeb.ca file directly

Webhooks

Configurez ces URLs dans votre channel manager pour synchroniser les réservations automatiquement.

Lodgify

https://locareo.com/api/webhooks/lodgify

Secret header: LODGIFY_WEBHOOK_SECRET

Guesty

https://locareo.com/api/webhooks/guesty

Secret header: GUESTY_WEBHOOK_SECRET

Hostaway

https://locareo.com/api/webhooks/hostaway

iCal Feed

Chaque propriété expose un flux iCal public pour la synchronisation des disponibilités.

GET https://locareo.com/api/ical/{propertyId}.ics

Mise à jour en temps réel. Compatible avec tous les channel managers et Google Calendar.

MCP Server

Le MCP Server Locareo permet aux assistants AI (Claude, GPT-4, etc.) de gérer vos annonces en langage naturel.

# Installation
npm install -g @locareo/mcp-server

# Configuration Claude Desktop
{
  "mcpServers": {
    "locareo": {
      "command": "locareo-mcp",
      "env": { "LOCAREO_API_KEY": "lk_xxx.yyy" }
    }
  }
}

# Outils disponibles
locareo_list_properties    — Liste vos hébergements
locareo_get_property       — Détails d'un hébergement
locareo_check_availability — Vérifier disponibilité
locareo_import_gbca        — Importer un fichier GBCA
locareo_export_gbca        — Exporter en GBCA
locareo_from_url           — URL → GBCA automatique
locareo_list_bookings      — Vos réservations
locareo_manage_keys        — Gérer clés API

Codes d'erreur

400Paramètre manquant ou invalide

401Clé API manquante ou invalide

403Scope insuffisant pour cette opération

404Ressource introuvable

422Fichier GBCA invalide (voir details[])

429Rate limit dépassé (60 req/min)

500Erreur serveur interne

Limites

Rate limit60 req/min par clé

Clés API par compte10 max

Taille fichier GBCA10 MB max

Photos par propriété50 max

Pagination max200 items