Documentation de l'API de données Airbnb

Utilisez l'API de données Airbnb BNBCalc pour obtenir des revenus de propriété, l'occupation, l'ADR, des listes comparables Airbnb actives, des percentiles, des indicateurs d'investissement et des URL de rapports hébergés pour des applications, des rapports, des souscriptions et des outils de gestion.

Spécification OpenAPI
URL de base
https://atlas.bnbcalc.com
En-tête de clé API
x-bnbcalc-api-key
Serveur MCP
https://atlas.bnbcalc.com/mcp
Mis à jour

Premiers pas

  1. 1

    Créez un compte BNBCalc et générez une clé API dans les paramètres de votre tableau de bord.

  2. 2

    Envoyez votre clé dans l'en-tête x-bnbcalc-api-key à chaque requête.

  3. 3

    POST a property's location and details to any analysis endpoint and read the JSON response, including the hosted report URL.

Tous les points de terminaison de l'API utilisent HTTPS et renvoient des réponses JSON. Conservez les clés API sur votre serveur, pas dans le code du navigateur ou du client mobile. Les itinéraires API externes sont actuellement limités à 100 requêtes par seconde et utilisent des codes de réponse HTTP standard pour indiquer le succès ou l'échec.

Importez la description OpenAPI 3.1 dans Postman, Insomnia ou un générateur de clients : https://www.bnbcalc.com/developers/openapi.json

Vous n'écrivez pas de code ? Utilisez plutôt BNBCalc de Claude, ChatGPT ou une autre application d'IA. Guide de configuration MCP

Authentification

Toutes les requêtes API nécessitent une authentification à l'aide d'une clé API. Les clés API sont liées à votre compte BNBCalc, doivent être conservées côté serveur et ne doivent jamais être exposées dans le code frontend. Incluez votre clé API dans l'en-tête de la requête comme indiqué ci-dessous :

HTTP

x-bnbcalc-api-key: YOUR_API_KEY

Vous pouvez générer des clés API en libre-service depuis la page de configuration de votre compte. Incluez l'en-tête x-bnbcalc-api-key dans chaque requête API pour vous authentifier.

Créer des analyses

  • AI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.
  • AI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.
  • Lorsqu'une étape d'IA ne peut pas être terminée, la réponse renvoie toujours 201 avec l'analyse valide et un tableau d'avertissements expliquant ce qui a été ignoré. Vérifiez les avertissements plutôt que de supposer que les résultats de l'IA sont toujours présents.
  • Chaque étape d'IA terminée ajoute 0,10 $ à l'appel. Les étapes d'IA qui échouent ou expirent ne sont jamais facturées, et /enhance est facturé uniquement pour les étapes d'IA qui se sont terminées, sans frais de base par appel.

POST /v1/external/analysis/create/buy

Créer une analyse d'achat

Créer une nouvelle analyse d'achat pour une propriété. Nécessite des détails sur la propriété, des informations sur l'emplacement et le prix d'achat.

Outil MCPcreate_buy_analysis

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumber

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)

Exemple : 27.7676

lngnumber

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)

Exemple : -82.6403

fullAddressstring

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)

Exemple : 4935 2nd Avenue North, St. Petersburg, FL 33703

Paramètres Requis

purchasePriceUSDnumber

Prix d'achat en USD

Exemple : 350000

bedroomsnumber

Nombre de chambres

Exemple : 3

bathroomsnumber

Nombre de salles de bains

Exemple : 2

accomodatesnumber

Nombre d'invités que la propriété peut accueillir

Exemple : 6

Paramètres Optionnels

monthlyRentUSDnumber

Loyer mensuel attendu en USD pour une location à long terme

Exemple : 2500

interestRatePercentagenumber

Pourcentage du taux d'intérêt (0-15)

Exemple : 5.1

downPaymentPercentagenumber

Pourcentage de paiement initial (0-40)

Exemple : 25

mortgageLengthnumber

Durée du prêt hypothécaire en années (0-30)

Exemple : 15

squareFeetnumber

Surface en pieds carrés de la propriété

Exemple : 1500

statestring

Nom de l'État

Exemple : Florida

citystring

Nom de la ville

Exemple : St. Petersburg

countystring

Nom du comté

Exemple : Pinellas County

postalCodestring

Code postal

Exemple : 33703

countrystring

Nom du pays

Exemple : United States

streetstring

Nom de la rue

Exemple : 2nd Avenue North

streetNumberstring

Numéro de rue

Exemple : 4935

unitstring

Numéro d'unité/appartement, le cas échéant

addAICompsboolean

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.

Exemple : true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Exemple : true

curl -X POST \
  'https://atlas.bnbcalc.com/v1/external/analysis/create/buy' \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}'

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "000000000000000000000000",
    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
    "currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
      "type": "Point",
      "coordinates": [
        -82.6403,
        27.7676
      ]
    },
    "revenue": {
      "p25": 48210,
      "p50": 58440,
      "p75": 63944.76398163934,
      "p90": 74280,
      "avg": 60310
    },
    "adr": {
      "p25": 214,
      "p50": 288,
      "p75": 364.73770491803276,
      "p90": 431,
      "avg": 318
    },
    "occupancy": {
      "p25": 0.38,
      "p50": 0.44,
      "p75": 0.48,
      "p90": 0.56,
      "avg": 0.46
    },
    "quartiles": {
      "25th_percentile": {
        "average_daily_rate": 214,
        "occupancy_rate": 38,
        "revenue": 48210
      },
      "50th_percentile": {
        "average_daily_rate": 288,
        "occupancy_rate": 44,
        "revenue": 58440
      },
      "75th_percentile": {
        "average_daily_rate": 364.73770491803276,
        "occupancy_rate": 48,
        "revenue": 63944.76398163934
      },
      "90th_percentile": {
        "average_daily_rate": 431,
        "occupancy_rate": 56,
        "revenue": 74280
      }
    },
    "comparables": [
      {
        "airbnbId": "12345678",
        "name": "Modern 4BR near downtown",
        "listingUrl": "https://www.airbnb.com/rooms/12345678",
        "bedrooms": 4,
        "bathrooms": 3,
        "accommodates": 10,
        "annualRevenueUSD": 68420,
        "occupancyRatePercentage": 52,
        "averageDailyRateUSD": 361,
        "distanceMiles": 0.4,
        "photo_urls": [
          "https://a0.muscache.com/im/pictures/example/cover.jpg",
          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
        ]
      }
    ],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 4,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOnePrincipalPaidUSD": 5635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
    "revenueBasis": "full_time_potential",
    "actualAnnualRevenue": {
      "p25": 24180,
      "p50": 36920,
      "p75": 47350,
      "p90": 58810,
      "average": 37640
    }
  }
}

POST /v1/external/analysis/create/arb

Créer une analyse d'arbitrage

Créez une nouvelle analyse d'arbitrage (arbitrage locatif) pour un bien immobilier. Utilise les mêmes champs obligatoires que l'analyse d'achat.

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumber

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)

Exemple : 27.7676

lngnumber

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)

Exemple : -82.6403

fullAddressstring

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)

Exemple : 4935 2nd Avenue North, St. Petersburg, FL 33703

Paramètres Requis

monthlyRentUSDnumber

Loyer mensuel attendu en USD pour une location à long terme

Exemple : 2500

bedroomsnumber

Nombre de chambres

Exemple : 3

bathroomsnumber

Nombre de salles de bains

Exemple : 2

accomodatesnumber

Nombre d'invités que la propriété peut accueillir

Exemple : 6

Paramètres Optionnels

purchasePriceUSDnumber

Prix d'achat en USD

Exemple : 350000

squareFeetnumber

Surface en pieds carrés de la propriété

Exemple : 1500

statestring

Nom de l'État

Exemple : Florida

citystring

Nom de la ville

Exemple : St. Petersburg

countystring

Nom du comté

Exemple : Pinellas County

postalCodestring

Code postal

Exemple : 33703

countrystring

Nom du pays

Exemple : United States

streetstring

Nom de la rue

Exemple : 2nd Avenue North

streetNumberstring

Numéro de rue

Exemple : 4935

unitstring

Numéro d'unité/appartement, le cas échéant

addAICompsboolean

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.

Exemple : true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Exemple : true

curl -X POST \
  'https://atlas.bnbcalc.com/v1/external/analysis/create/arb' \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}'

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "000000000000000000000000",
    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
    "currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
      "type": "Point",
      "coordinates": [
        -82.6403,
        27.7676
      ]
    },
    "revenue": {
      "p25": 48210,
      "p50": 58440,
      "p75": 63944.76398163934,
      "p90": 74280,
      "avg": 60310
    },
    "adr": {
      "p25": 214,
      "p50": 288,
      "p75": 364.73770491803276,
      "p90": 431,
      "avg": 318
    },
    "occupancy": {
      "p25": 0.38,
      "p50": 0.44,
      "p75": 0.48,
      "p90": 0.56,
      "avg": 0.46
    },
    "quartiles": {
      "25th_percentile": {
        "average_daily_rate": 214,
        "occupancy_rate": 38,
        "revenue": 48210
      },
      "50th_percentile": {
        "average_daily_rate": 288,
        "occupancy_rate": 44,
        "revenue": 58440
      },
      "75th_percentile": {
        "average_daily_rate": 364.73770491803276,
        "occupancy_rate": 48,
        "revenue": 63944.76398163934
      },
      "90th_percentile": {
        "average_daily_rate": 431,
        "occupancy_rate": 56,
        "revenue": 74280
      }
    },
    "comparables": [
      {
        "airbnbId": "12345678",
        "name": "Modern 4BR near downtown",
        "listingUrl": "https://www.airbnb.com/rooms/12345678",
        "bedrooms": 4,
        "bathrooms": 3,
        "accommodates": 10,
        "annualRevenueUSD": 68420,
        "occupancyRatePercentage": 52,
        "averageDailyRateUSD": 361,
        "distanceMiles": 0.4,
        "photo_urls": [
          "https://a0.muscache.com/im/pictures/example/cover.jpg",
          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
        ]
      }
    ],
    "monthlyRentUSD": 2000,
    "yearOneRentUSD": 24000,
    "monthlyRevenueUSD": 13432.825977452352,
    "monthlyExpensesUSD": 2263.6108575197586,
    "yearOneRevenueUSD": 161193.91172942822,
    "yearOneOperatingIncomeUSD": 134030.58143919113,
    "yearOneCashFlowUSD": 110030.58143919116,
    "yearOneCashOnCashPercentage": 1317.415965507557,
    "totalCashInvestment": 8352
  }
}

POST /v1/external/analysis/create/owned

Créer une analyse personnelle

Créer une nouvelle analyse pour un bien immobilier détenu. Utilise les mêmes champs obligatoires que l'analyse d'achat.

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumber

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)

Exemple : 27.7676

lngnumber

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)

Exemple : -82.6403

fullAddressstring

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)

Exemple : 4935 2nd Avenue North, St. Petersburg, FL 33703

Paramètres Requis

purchasePriceUSDnumber

Prix d'achat en USD

Exemple : 350000

downPaymentPercentagenumber

Pourcentage de paiement initial (0-40)

Exemple : 20

interestRatePercentagenumber

Pourcentage du taux d'intérêt (0-15)

Exemple : 5.1

mortgageLengthnumber

Durée du prêt hypothécaire en années (0-30)

Exemple : 30

yearsRemainingOnMortgagenumber

Années restantes sur l'hypothèque (Ne peut pas dépasser la durée de l'hypothèque)

bedroomsnumber

Nombre de chambres

Exemple : 3

bathroomsnumber

Nombre de salles de bains

Exemple : 2

accomodatesnumber

Nombre d'invités que la propriété peut accueillir

Exemple : 6

Paramètres Optionnels

monthlyRentUSDnumber

Loyer mensuel attendu en USD pour une location à long terme

Exemple : 2500

squareFeetnumber

Surface en pieds carrés de la propriété

Exemple : 1500

statestring

Nom de l'État

Exemple : Florida

citystring

Nom de la ville

Exemple : St. Petersburg

countystring

Nom du comté

Exemple : Pinellas County

postalCodestring

Code postal

Exemple : 33703

countrystring

Nom du pays

Exemple : United States

streetstring

Nom de la rue

Exemple : 2nd Avenue North

streetNumberstring

Numéro de rue

Exemple : 4935

unitstring

Numéro d'unité/appartement, le cas échéant

addAICompsboolean

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.

Exemple : true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Exemple : true

curl -X POST \
  'https://atlas.bnbcalc.com/v1/external/analysis/create/owned' \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}'

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "000000000000000000000000",
    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
    "currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
      "type": "Point",
      "coordinates": [
        -82.6403,
        27.7676
      ]
    },
    "revenue": {
      "p25": 48210,
      "p50": 58440,
      "p75": 63944.76398163934,
      "p90": 74280,
      "avg": 60310
    },
    "adr": {
      "p25": 214,
      "p50": 288,
      "p75": 364.73770491803276,
      "p90": 431,
      "avg": 318
    },
    "occupancy": {
      "p25": 0.38,
      "p50": 0.44,
      "p75": 0.48,
      "p90": 0.56,
      "avg": 0.46
    },
    "quartiles": {
      "25th_percentile": {
        "average_daily_rate": 214,
        "occupancy_rate": 38,
        "revenue": 48210
      },
      "50th_percentile": {
        "average_daily_rate": 288,
        "occupancy_rate": 44,
        "revenue": 58440
      },
      "75th_percentile": {
        "average_daily_rate": 364.73770491803276,
        "occupancy_rate": 48,
        "revenue": 63944.76398163934
      },
      "90th_percentile": {
        "average_daily_rate": 431,
        "occupancy_rate": 56,
        "revenue": 74280
      }
    },
    "comparables": [
      {
        "airbnbId": "12345678",
        "name": "Modern 4BR near downtown",
        "listingUrl": "https://www.airbnb.com/rooms/12345678",
        "bedrooms": 4,
        "bathrooms": 3,
        "accommodates": 10,
        "annualRevenueUSD": 68420,
        "occupancyRatePercentage": 52,
        "averageDailyRateUSD": 361,
        "distanceMiles": 0.4,
        "photo_urls": [
          "https://a0.muscache.com/im/pictures/example/cover.jpg",
          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
        ]
      }
    ],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 5.1,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOnePrincipalPaidUSD": 5635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
    "revenueBasis": "full_time_potential",
    "actualAnnualRevenue": {
      "p25": 24180,
      "p50": 36920,
      "p75": 47350,
      "p90": 58810,
      "average": 37640
    }
  }
}

POST /v1/external/analysis/create/cohost

Créer une analyse Cohost

Créer l'historique des co-hôtes

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumber

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)

Exemple : 27.7676

lngnumber

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)

Exemple : -82.6403

fullAddressstring

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)

Exemple : 4935 2nd Avenue North, St. Petersburg, FL 33703

Paramètres Requis

bedroomsnumber

Nombre de chambres

Exemple : 3

bathroomsnumber

Nombre de salles de bains

Exemple : 2

accomodatesnumber

Nombre d'invités que la propriété peut accueillir

Exemple : 6

Paramètres Optionnels

cohostCommissionPercentagenumber

Pourcentage de commission du co-hôte

Exemple : 10

squareFeetnumber

Surface en pieds carrés de la propriété

Exemple : 1500

statestring

Nom de l'État

Exemple : Florida

citystring

Nom de la ville

Exemple : St. Petersburg

countystring

Nom du comté

Exemple : Pinellas County

postalCodestring

Code postal

Exemple : 33703

countrystring

Nom du pays

Exemple : United States

streetstring

Nom de la rue

Exemple : 2nd Avenue North

streetNumberstring

Numéro de rue

Exemple : 4935

unitstring

Numéro d'unité/appartement, le cas échéant

addAICompsboolean

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.

Exemple : true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Exemple : true

curl -X POST \
  'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost' \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}'

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "000000000000000000000000",
    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
    "currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
      "type": "Point",
      "coordinates": [
        -82.6403,
        27.7676
      ]
    },
    "revenue": {
      "p25": 48210,
      "p50": 58440,
      "p75": 63944.76398163934,
      "p90": 74280,
      "avg": 60310
    },
    "adr": {
      "p25": 214,
      "p50": 288,
      "p75": 364.73770491803276,
      "p90": 431,
      "avg": 318
    },
    "occupancy": {
      "p25": 0.38,
      "p50": 0.44,
      "p75": 0.48,
      "p90": 0.56,
      "avg": 0.46
    },
    "quartiles": {
      "25th_percentile": {
        "average_daily_rate": 214,
        "occupancy_rate": 38,
        "revenue": 48210
      },
      "50th_percentile": {
        "average_daily_rate": 288,
        "occupancy_rate": 44,
        "revenue": 58440
      },
      "75th_percentile": {
        "average_daily_rate": 364.73770491803276,
        "occupancy_rate": 48,
        "revenue": 63944.76398163934
      },
      "90th_percentile": {
        "average_daily_rate": 431,
        "occupancy_rate": 56,
        "revenue": 74280
      }
    },
    "comparables": [
      {
        "airbnbId": "12345678",
        "name": "Modern 4BR near downtown",
        "listingUrl": "https://www.airbnb.com/rooms/12345678",
        "bedrooms": 4,
        "bathrooms": 3,
        "accommodates": 10,
        "annualRevenueUSD": 68420,
        "occupancyRatePercentage": 52,
        "averageDailyRateUSD": 361,
        "distanceMiles": 0.4,
        "photo_urls": [
          "https://a0.muscache.com/im/pictures/example/cover.jpg",
          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
        ]
      }
    ],
    "yearOneRevenueUSD": 161193.91172942825,
    "yearOneCohostReturnUSD": 116059.61644518835,
    "yearOneCohostCommissionUSD": 32238.78234588565
  }
}

Enrichissement IA

POST /v1/external/analysis/enhance

Améliorer l'analyse avec l'IA

Exécute un enrichissement par l'IA sur une analyse que vous avez déjà créée et renvoie l'analyse recalculée. Utilisez cette option lorsque vous souhaitez que des comparables sélectionnés par l'IA ou des estimations de dépenses par l'IA soient appliqués après coup, ou lorsque vous préférez que l'appel de création d'origine soit rapide.

  • AI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.
  • AI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.
  • Lorsqu'une étape d'IA ne peut pas être terminée, la réponse renvoie toujours 201 avec l'analyse valide et un tableau d'avertissements expliquant ce qui a été ignoré. Vérifiez les avertissements plutôt que de supposer que les résultats de l'IA sont toujours présents.
  • Chaque étape d'IA terminée ajoute 0,10 $ à l'appel. Les étapes d'IA qui échouent ou expirent ne sont jamais facturées, et /enhance est facturé uniquement pour les étapes d'IA qui se sont terminées, sans frais de base par appel.
  • Si chaque étape d'IA que vous avez demandée échoue, l'appel est gratuit et la réponse ne contient que des avertissements, sans données. Votre analyse stockée reste inchangée dans ce cas, donc la copie que vous avez déjà est toujours d'actualité. Les points de terminaison de création retournent toujours des données, car leurs frais de base couvrent le rapport lui-même.

Paramètres Requis

analysisIdstring

The _id of an analysis previously created with your API key

Exemple : 000000000000000000000000

Paramètres Optionnels

addAICompsboolean

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.

Exemple : true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Exemple : true

curl -X POST \
  'https://atlas.bnbcalc.com/v1/external/analysis/enhance' \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "analysisId": "000000000000000000000000",
  "addAIComps": true,
  "addAIExpenseEstimates": true
}'

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "000000000000000000000000",
    "url": "https://www.bnbcalc.com/analysis/example-property/000000000000000000000000",
    "currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
      "type": "Point",
      "coordinates": [
        -82.6403,
        27.7676
      ]
    },
    "revenue": {
      "p25": 48210,
      "p50": 58440,
      "p75": 63944.76398163934,
      "p90": 74280,
      "avg": 60310
    },
    "adr": {
      "p25": 214,
      "p50": 288,
      "p75": 364.73770491803276,
      "p90": 431,
      "avg": 318
    },
    "occupancy": {
      "p25": 0.38,
      "p50": 0.44,
      "p75": 0.48,
      "p90": 0.56,
      "avg": 0.46
    },
    "quartiles": {
      "25th_percentile": {
        "average_daily_rate": 214,
        "occupancy_rate": 38,
        "revenue": 48210
      },
      "50th_percentile": {
        "average_daily_rate": 288,
        "occupancy_rate": 44,
        "revenue": 58440
      },
      "75th_percentile": {
        "average_daily_rate": 364.73770491803276,
        "occupancy_rate": 48,
        "revenue": 63944.76398163934
      },
      "90th_percentile": {
        "average_daily_rate": 431,
        "occupancy_rate": 56,
        "revenue": 74280
      }
    },
    "comparables": [
      {
        "airbnbId": "12345678",
        "name": "Modern 4BR near downtown",
        "listingUrl": "https://www.airbnb.com/rooms/12345678",
        "bedrooms": 4,
        "bathrooms": 3,
        "accommodates": 10,
        "annualRevenueUSD": 68420,
        "occupancyRatePercentage": 52,
        "averageDailyRateUSD": 361,
        "distanceMiles": 0.4,
        "photo_urls": [
          "https://a0.muscache.com/im/pictures/example/cover.jpg",
          "https://a0.muscache.com/im/pictures/example/living-room.jpg",
          "https://a0.muscache.com/im/pictures/example/kitchen.jpg"
        ]
      }
    ],
    "propertyTaxPercentage": 0.75,
    "internetAndTVUSD": 90,
    "waterUSD": 85,
    "electricUSD": 180,
    "propertyInsuranceUSD": 210,
    "HOAUSD": 0,
    "repairsUSD": 125,
    "suppliesUSD": 60,
    "cleaningCostPercentage": 8.5,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141
  },
  "aiComps": {
    "selectedCompIds": [
      "12345678",
      "23456789"
    ],
    "benchmark": {
      "annualRevenueUSD": 63944.76398163934,
      "ratePerNightUSD": 364.73770491803276,
      "occupancyRatePercentage": 48
    },
    "rationale": "Selected comparables matching bedroom count, pool and waterfront access.",
    "warnings": [],
    "applied": true
  }
}

Comportement de l'enrichissement AI

L'enrichissement par l'IA est facultatif par requête via addAIComps et addAIExpenseEstimates, et chaque étape de l'IA est limitée dans le temps et échoue ouvertement. Une requête qui demandait de l'IA renvoie toujours 201 avec une analyse complète et entièrement recalculée ; tout ce qui n'a pas pu s'exécuter est signalé dans le tableau d'avertissements de niveau supérieur au lieu de générer une erreur.

Temporisations et limites de taux

  • Le travail d'IA dispose d'un budget de 90 secondes mesuré à partir du début de la requête, et non à partir du moment où l'étape d'IA commence, donc la géocodification et la création d'analyse y contribuent. Lorsque le budget est épuisé, l'analyse est renvoyée sans l'étape d'IA inachevée et un avertissement de délai d'attente.
  • Réglez le timeout de votre client sur au moins 300 secondes. La plupart des appels AI retournent bien avant la fin du budget, mais un client qui abandonne avant la date limite du serveur transforme une analyse facturable et complète en une réponse perdue.
  • Un appel de modèle nécessite au moins 45 secondes de budget restant pour démarrer. Une requête qui passe la majeure partie de son budget à attendre les photos de l'annonce renvoie ai_comps_timed_out sans appeler le modèle plutôt que de lancer un run qu'il ne pourrait pas finir.
  • Les requêtes qui activent un flag AI sont soumises à une limite de taux par clé API : 10 par minute, avec au maximum 2 en cours simultanément. Le dépassement renvoie 429 avec un en-tête Retry-After, et X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset sont définis sur chaque requête AI. Les appels sans flag AI ne sont pas affectés par cette limite.
  • Pour retenter une étape d'IA ignorée, appelez POST /v1/external/analysis/enhance avec le même analysisId au lieu de créer à nouveau l'analyse. Enhance n'entraîne aucuns frais d'appel de base, donc une nouvelle tentative ne coûte que les étapes d'IA qui s'achèvent.

Avertissements de réponse

Une réponse 201 peut toujours contenir un tableau d'avertissements. Traitez-le comme l'enregistrement de ce qui n'a pas été exécuté et vérifiez-le avant de supposer que les résultats de l'IA sont présents. Chaque étape signalée ici a été ignorée, et les étapes ignorées ne sont jamais facturées.

ai_comps_requires_user_scoped_api_key
Les AI comps nécessitent une clé API liée à un compte utilisateur. La clé n'a pas pu être rattachée à un propriétaire, donc le sélecteur de comparables ne s'est jamais exécuté.
ai_comps_unavailable_for_property
Les AI comps sont disponibles uniquement pour les biens situés aux États-Unis, et l'analyse stockée est hors de ce périmètre.
ai_comps_photos_not_ready
Les photos utilisables des annonces pour l'adresse n'étaient pas prêtes à temps : aucune n'a été trouvée, trop peu étaient utilisables ou la galerie était encore en cours de traitement lorsque le budget a été épuisé. Les photos sont collectées en arrière-plan après la création d'une analyse, de sorte que réessayer avec /enhance peu de temps après réussit généralement.
ai_comps_timed_out
Le budget AI a été épuisé avant le retour du modèle, donc les comparables déterministes et la projection de revenus ont été conservés.
ai_comps_benchmark_fallback
Le modèle s'est exécuté mais a sélectionné trop peu de comparables pour constituer un benchmark, donc la projection de revenus existante a été conservée. Rien n'a été écrit dans l'analyse et l'étape n'a pas été facturée.
ai_comps_model_unavailable
Le fournisseur du modèle n'était pas disponible. Ceci est transitoire, alors réessayez avec /enhance.
ai_comps_already_applied
Cette analyse dispose déjà d'un benchmark IA valide : rien n'a été réexécuté ni facturé. Modifier le bien l'invalide, et l'appel suivant s'exécute réellement.
ai_comps_run_in_progress
Une autre exécution IA de comparables travaille déjà sur cette analyse. Attendez avant de réessayer : l'exécution détient un verrouillage jusqu'à 10 minutes.
ai_comps_analysis_changed
L'analyse a été modifiée pendant l'exécution du modèle ; le benchmark n'a donc pas été écrit plutôt que d'écraser les valeurs plus récentes. Réessayez avec /enhance.
ai_comps_forbidden
L'analyse n'a pas été créée avec cette clé API, les AI comps n'ont donc pas pu s'exécuter dessus.
ai_comps_failed
Les AI comps n'ont pas pu être complétés pour une autre raison. L'analyse elle-même est valide et inchangée.
ai_expense_estimates_timed_out
Le budget AI a été épuisé avant le retour de l'estimateur de dépenses, donc les charges d'exploitation par défaut ont été conservées.
ai_expense_estimates_no_proposals
L'estimateur n'a produit aucune proposition de dépenses pour ce bien, donc aucune charge d'exploitation n'a été modifiée.
ai_expense_estimates_stale_preview
L'analyse a changé pendant la préparation de l'estimation, elle a donc été rejetée plutôt qu'appliquée à des entrées obsolètes. Réessayez avec /enhance.
ai_expense_estimates_model_unavailable
Le fournisseur du modèle n'était pas disponible. Ceci est transitoire, alors réessayez avec /enhance.
ai_expense_estimates_already_applied
Cette analyse dispose déjà de charges estimées par IA : rien n'a été réexécuté ni facturé.
ai_expense_estimates_unavailable_for_property
Aucun champ de charges d'exploitation de cette analyse n'était éligible à l'estimation par IA ; les charges par défaut ont donc été conservées.
ai_expense_estimates_forbidden
L'analyse n'a pas été créée avec cette clé API, les estimations de charges par IA n'ont donc pas pu s'exécuter dessus.
ai_expense_estimates_failed
Les estimations de dépenses AI n'ont pas pu être appliquées. L'analyse conserve ses charges d'exploitation par défaut.

Fondez la correspondance sur les préfixes ai_comps_ et ai_expense_estimates_ plutôt que sur la chaîne exacte : tout autre code commençant par ces préfixes signifie que l'étape a échoué, n'a pas été appliquée et n'a pas été facturée.

Réponse d'exemple

{
  "success": true,
  "warnings": [
    "ai_comps_photos_not_ready"
  ],
  "data": {
    "_id": "000000000000000000000000",
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607
  }
}

aiComps.warnings

Le tableau imbriqué aiComps.warnings est un signal distinct de celui de premier niveau : il décrit la qualité du pool de comparables avec lequel le modèle a travaillé, et non une étape ayant échoué. Consultez aiComps.applied pour savoir si le benchmark AI a effectivement été écrit dans l'analyse.

thin_benchmark_pool
Moins de quatre comparables soutiennent le benchmark, qui repose donc sur un petit échantillon.
no_benchmark_comps
Aucun comparable n'a passé la sélection. Le benchmark est vide et la projection de revenus est restée inchangée.
ai_benchmark_fallback_to_projected_revenue
Moins de trois comparables ont été sélectionnés, donc la projection de revenus existante a été conservée au lieu du benchmark AI. C'est le même résultat signalé au niveau supérieur sous ai_comps_benchmark_fallback.
minimum_benchmark_pool_backfill
Le pool de benchmark a été complété avec des comparables que le modèle n'avait pas choisis afin d'atteindre le nombre minimum.

Facturation lorsque l'AI est partielle

Chaque étape d'IA terminée ajoute 0,10 $ à l'appel. Les étapes qui expirent, échouent ou reviennent à la projection existante ne sont pas facturées (aiComps.applied défini sur false signifie que les comparaisons d'IA n'ont pas été facturées), et un appel /enhance où chaque étape demandée a été ignorée n'est pas facturé du tout.

Limites de débit

Les limites comptent par IP appelante, sauf indication contraire dans une ligne. Les réponses limitées comportent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une requête dépassant une limite renvoie 429 avec un en-tête Retry-After en secondes et n'est jamais facturée, attendez donc ce délai avant de réessayer.

100 par seconde
Chaque route /v1/external.
5 par minute
POST /v1/external/analysis/enhance et exécutions de Listing Optimizer (run_listing_optimization).
10 par minute
Requêtes qui définissent addAIComps ou addAIExpenseEstimates, par clé d'API, avec au plus 2 en cours.
10 à 60 par minute
Listes en direct 10; détails de la propriété, estimations de loyer et compte 30 ; heures de participation matérielle d'enregistrement 60.
2 000 par jour
Recherches de données (estimations de revenus, tarifs par nuit, comparables, annonces et photos, annonces en direct, détails de la propriété et estimations de loyer) par compte, partagées par l'API REST et le serveur MCP, et jusqu'à 2 500 lignes d'annonce par jour. Le plafond est réinitialisé à 00:00 UTC.

Codes d'erreur

L'API BNBCalc utilise les codes d'état HTTP standard pour indiquer la réussite ou l'échec des requêtes. Les requêtes réussies renvoient des codes 2xx, tandis que les erreurs renvoient des codes 4xx ou 5xx avec des informations supplémentaires dans le corps de la réponse. Les requêtes en échec (4xx ou 5xx) ne sont jamais facturées.

201
Créé : l'analyse a été créée ou améliorée et se trouve dans la réponse
400
Mauvaise demande - Paramètres invalides
401
Non autorisé - Clé API invalide
402
Payment Required - Le compte de la clé n'a pas d'abonnement API actif ou n'a plus de crédits Listing Optimizer
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - L'analyse, l'annonce ou l'emplacement demandé est introuvable
409
Conflict - Une exécution IA ou Listing Optimizer est déjà en cours, l'analyse a changé depuis votre lecture ou le rapport n'est pas encore prêt
429
Trop de requêtes - limite d'itinéraire API externe dépassée
500
Erreur interne du serveur
502
Bad Gateway - The AI model returned an unusable response
503
Service Unavailable - Un modèle IA ou la source des annonces est temporairement indisponible ; réessayez plus tard
Vérifier l'état de l'API

Guides API

Tarification API

Découvrez le coût de l'API BNBCalc : $0 par mois, $0.20 par rapportation et $0.10 par étape d'IA complétée.

Cas d'utilisation API

Découvrez comment les plateformes PropTech, investisseurs, prêteurs, opérateurs et analystes utilisent l'API dans des workflows de production.

Couverture des données

Comprenez la couverture internationale des propriétés, les estimations basées sur des comparables, les entrées de localisation et où l'API s'intègre.

Comparaison d'API

Découvrez comment l'API BNBCalc se compare à l'API d'AirDNA et à d'autres API de données Airbnb en matière d'accès, de modèle de tarification et de résultats.

Google Sheets

Analysez une liste d'adresses dans Google Sheets avec un court Apps Script.

Serveur MCP

Connectez Claude, Cursor ou VS Code à BNBCalc et exécutez des estimations de revenus et des analyses d'accords à partir de votre assistant IA.

Guide de configuration MCP

Connectez Claude, ChatGPT, Claude Code, Cursor ou VS Code au serveur MCP, étape par étape.

Référence MCP

Comment le serveur MCP s'authentifie, chaque outil avec son prix, l'approbation des outils payants et les limites.

Journal des modifications

Ce qui a changé dans l'API REST et le serveur MCP, du plus récent au plus ancien.

État

Vérifications en direct de l'API REST et du serveur MCP.