Documentation de l'API de données Airbnb

Bienvenue dans l'API BNBCalc. Cette documentation vous aide à intégrer l'analyse des propriétés de location à court terme dans votre application.

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.

Premiers pas

Pour commencer à utiliser l'API de données Airbnb BNBCalc, vous devez :

1. Créez un compte BNBCalc ou connectez-vous à votre compte existant

2. Accédez aux paramètres de votre compte pour générer une clé API

3. Incluez votre clé API dans toutes les requêtes API en utilisant l'en-tête x-bnbcalc-api-key.

4. Commencez à faire des demandes pour accéder aux données et analyses immobilières.

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.

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 :

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.

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.

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.

When an AI step cannot complete, the response still returns 200 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.

Each AI function that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI functions that completed — it carries no base call fee.

Paramètres de Localisation (Conditionnel)

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

latnumberconditionnel

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

lngnumberconditionnel

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

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

purchasePriceUSDnumberobligatoire

Prix d'achat en USD(e.g., 350000)

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

monthlyRentUSDnumberoptionnel

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

interestRatePercentagenumberoptionnel

Pourcentage du taux d'intérêt (0-15)(e.g., 5.1)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

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

addAICompsbooleanoptionnel

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

addAIExpenseEstimatesbooleanoptionnel

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Demande d'exemple

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/buy',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/buy',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

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,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10
  }
}

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.

latnumberconditionnel

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

lngnumberconditionnel

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

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

monthlyRentUSDnumberobligatoire

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

purchasePriceUSDnumberoptionnel

Prix d'achat en USD(e.g., 350000)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

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

addAICompsbooleanoptionnel

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

addAIExpenseEstimatesbooleanoptionnel

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Demande d'exemple

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/arb',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/arb',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

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.

latnumberconditionnel

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

lngnumberconditionnel

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

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

purchasePriceUSDnumberobligatoire

Prix d'achat en USD(e.g., 350000)

downPaymentPercentagenumberobligatoire

Pourcentage de paiement initial (0-40)(e.g., 20)

interestRatePercentagenumberobligatoire

Pourcentage du taux d'intérêt (0-15)(e.g., 5.1)

mortgageLengthnumberobligatoire

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

yearsRemainingOnMortgagenumberobligatoire

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

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

monthlyRentUSDnumberoptionnel

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

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

addAICompsbooleanoptionnel

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

addAIExpenseEstimatesbooleanoptionnel

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Demande d'exemple

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/owned',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/owned',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

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,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10
  }
}

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.

latnumberconditionnel

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

lngnumberconditionnel

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

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

cohostCommissionPercentagenumberoptionnel

Pourcentage de commission du co-hôte(e.g., 10)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

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

addAICompsbooleanoptionnel

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

addAIExpenseEstimatesbooleanoptionnel

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Demande d'exemple

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

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
  }
}

POST/v1/external/analysis/enhance

Enhance Analysis with AI

Runs AI enrichment against an analysis you already created and returns the recalculated analysis. Use this when you want AI-selected comparables or AI expense estimates applied after the fact, or when you would rather keep the original create call fast.

Si toutes les fonctions IA demandées échouent, l'appel est gratuit et la réponse ne contient que warnings, sans data. Votre analyse stockée reste alors inchangée : la copie que vous avez déjà est toujours à jour. Les endpoints de création renvoient toujours data, car leurs frais de base couvrent le rapport lui-même.

Paramètres Requis

analysisIdstringobligatoire

The _id of an analysis previously created with your API key(e.g., 000000000000000000000000)

Paramètres Optionnels

addAICompsbooleanoptionnel

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

addAIExpenseEstimatesbooleanoptionnel

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Demande d'exemple

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/enhance',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "analysisId": "000000000000000000000000",
  "addAIComps": true,
  "addAIExpenseEstimates": true
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "analysisId": "000000000000000000000000",
  "addAIComps": true,
  "addAIExpenseEstimates": true
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/enhance',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

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 AI est activable par requête via addAIComps et addAIExpenseEstimates, et chaque étape AI est limitée dans le temps et échoue en mode ouvert. Une requête qui demandait de l'AI renvoie tout de même un 200 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 warnings de niveau supérieur au lieu de provoquer une erreur.

Temporisations et limites de taux

Le travail AI dispose d'un budget de 90 secondes mesuré depuis le début de la requête, et non depuis le lancement de l'étape AI — la géocodification et la création de l'analyse sont comptées dedans. Quand le budget est épuisé, l'analyse est renvoyée sans l'étape AI inachevée et avec un avertissement de timeout.

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 relancer une étape AI ignorée, appelez POST /v1/external/analysis/enhance avec le même analysisId plutôt que de recréer l'analyse. Enhance n'entraîne pas de frais d'appel de base, donc une nouvelle tentative ne coûte que les fonctions AI qui s'exécutent.

Avertissements de réponse

Une réponse 200 peut quand même contenir un tableau warnings. Considérez-le comme l'enregistrement de ce qui n'a pas été exécuté et vérifiez-le avant de supposer que les résultats AI 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 exploitables de l'annonce pour l'adresse n'étaient pas prêtes à temps — aucune trouvée, trop peu exploitables, ou la galerie était encore en cours de traitement lorsque le budget a expiré. Les photos sont rassemblées en arrière-plan après la création d'une analyse, donc réessayer avec /enhance peu 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 de modèle était indisponible. C'est transitoire — 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 d'AI comps traite déjà cette analyse. Attendez avant de réessayer : l'exécution conserve un verrou pendant 10 minutes maximum.

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 de modèle était indisponible. C'est transitoire — 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 fonction AI complétée ajoute $0.10 à l'appel. Les étapes qui expirent, échouent ou reviennent à la projection existante ne sont pas facturées — aiComps.applied à false signifie que les AI comps n'ont pas été facturés — et un appel /enhance où toutes les étapes demandées ont été ignorées n'est pas facturé du tout.

Codes d'erreur

L'API BNBCalc utilise des codes d'état de réponse HTTP standard pour indiquer le succès ou l'échec des requêtes API. Les rapports créés avec succès renvoient des codes 2xx, tandis que les erreurs renvoient des codes 4xx ou 5xx avec des informations d'erreur supplémentaires dans le corps de la réponse. Vous serez facturé uniquement pour les rapports créés avec succès.

200

Succès

400

Mauvaise demande - Paramètres invalides

401

Non autorisé - Clé API invalide

403

Forbidden - The analysis does not belong to your API key, or AI estimates are disabled

404

Not Found - No analysis matches the supplied analysisId

409

Conflict - An AI run is already in progress for this analysis, or its values changed mid-request

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 - The AI model is temporarily unavailable