Documentazione API dei dati di Airbnb

Utilizza l'API dei dati di Airbnb BNBCalc per ottenere reddito di proprietà, occupazione, ADR, inserzioni comparabili Airbnb attive, percentili, metriche di investimento e URL di rapporti ospitati per app, report, underwriting e strumenti di gestione.

Specifiche OpenAPI
URL di base
https://atlas.bnbcalc.com
Intestazione chiave API
x-bnbcalc-api-key
Server MCP
https://atlas.bnbcalc.com/mcp
Aggiornato

Primi passi

  1. 1

    Crea un account BNBCalc e genera una chiave API nelle impostazioni del tuo dashboard.

  2. 2

    Invia la tua chiave nell'header x-bnbcalc-api-key in ogni richiesta.

  3. 3

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

Tutti gli endpoint API utilizzano HTTPS e restituiscono risposte JSON. Mantieni le chiavi API sul tuo server, non nel codice del browser o nel client mobile. Le rotte API esterne sono attualmente limitate a 100 richieste al secondo e utilizzano codici di risposta HTTP standard per indicare il successo o il fallimento.

Importa la descrizione OpenAPI 3.1 in Postman, Insomnia o un client generator: https://www.bnbcalc.com/developers/openapi.json

Non stai scrivendo codice? Usa BNBCalc di Claude, ChatGPT o un'altra app AI invece. Guida alla configurazione MCP

Autenticazione

Tutte le richieste API richiedono autenticazione utilizzando una chiave API. Le chiavi API sono collegate al tuo account BNBCalc, devono essere mantenute lato server e non devono mai essere esposte nel codice frontend. Includi la tua chiave API nell'intestazione della richiesta come mostrato di seguito:

HTTP

x-bnbcalc-api-key: YOUR_API_KEY

Puoi generare le chiavi API autonomamente dalla pagina delle impostazioni del tuo account. Includi l'intestazione x-bnbcalc-api-key in ogni richiesta API per autenticarti.

Crea analisi

  • 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.
  • Quando un passaggio IA non può essere completato, la risposta restituisce comunque 201 con l'analisi valida e un array di avvisi che spiega cosa è stato saltato. Controlla gli avvisi invece di presumere che i risultati dell'IA siano sempre presenti.
  • Ogni passaggio AI completato aggiunge $0.10 alla chiamata. I passaggi AI che falliscono o scadono non vengono mai addebitati e /enhance viene fatturato solo per i passaggi AI completati, senza costi di base per chiamata.

POST /v1/external/analysis/create/buy

Crea analisi di acquisto

Creare una nuova analisi d'acquisto per una proprietà. Richiede dettagli della proprietà, informazioni sulla posizione e prezzo d'acquisto.

Strumento MCPcreate_buy_analysis

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumber

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)

Esempio: 27.7676

lngnumber

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)

Esempio: -82.6403

fullAddressstring

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)

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

Parametri Obbligatori

purchasePriceUSDnumber

Prezzo di acquisto in USD

Esempio: 350000

bedroomsnumber

Numero di camere da letto

Esempio: 3

bathroomsnumber

Numero di bagni

Esempio: 2

accomodatesnumber

Numero di ospiti che la proprietà può accogliere

Esempio: 6

Parametri Opzionali

monthlyRentUSDnumber

Affitto mensile previsto in USD per un affitto a lungo termine

Esempio: 2500

interestRatePercentagenumber

Percentuale del tasso d'interesse (0-15)

Esempio: 5.1

downPaymentPercentagenumber

Percentuale di acconto (0-40)

Esempio: 25

mortgageLengthnumber

Durata del mutuo in anni (0-30)

Esempio: 15

squareFeetnumber

Superficie in piedi quadrati della proprietà

Esempio: 1500

statestring

Nome dello stato

Esempio: Florida

citystring

Nome della città

Esempio: St. Petersburg

countystring

Nome della contea

Esempio: Pinellas County

postalCodestring

Codice postale

Esempio: 33703

countrystring

Nome del paese

Esempio: United States

streetstring

Nome della strada

Esempio: 2nd Avenue North

streetNumberstring

Numero civico

Esempio: 4935

unitstring

Numero dell'unità o dell'appartamento, se applicabile

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.

Esempio: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

Risposta di esempio

{
  "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

Crea analisi di arbitraggio

Crea una nuova analisi di arbitraggio (arbitraggio da affitto) per una proprietà. Utilizza gli stessi campi obbligatori dell'analisi d'acquisto.

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumber

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)

Esempio: 27.7676

lngnumber

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)

Esempio: -82.6403

fullAddressstring

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)

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

Parametri Obbligatori

monthlyRentUSDnumber

Affitto mensile previsto in USD per un affitto a lungo termine

Esempio: 2500

bedroomsnumber

Numero di camere da letto

Esempio: 3

bathroomsnumber

Numero di bagni

Esempio: 2

accomodatesnumber

Numero di ospiti che la proprietà può accogliere

Esempio: 6

Parametri Opzionali

purchasePriceUSDnumber

Prezzo di acquisto in USD

Esempio: 350000

squareFeetnumber

Superficie in piedi quadrati della proprietà

Esempio: 1500

statestring

Nome dello stato

Esempio: Florida

citystring

Nome della città

Esempio: St. Petersburg

countystring

Nome della contea

Esempio: Pinellas County

postalCodestring

Codice postale

Esempio: 33703

countrystring

Nome del paese

Esempio: United States

streetstring

Nome della strada

Esempio: 2nd Avenue North

streetNumberstring

Numero civico

Esempio: 4935

unitstring

Numero dell'unità o dell'appartamento, se applicabile

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.

Esempio: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

Risposta di esempio

{
  "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

Crea un'analisi personale

Crea una nuova analisi della proprietà posseduta. Utilizza gli stessi campi obbligatori dell'analisi di acquisto.

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumber

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)

Esempio: 27.7676

lngnumber

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)

Esempio: -82.6403

fullAddressstring

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)

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

Parametri Obbligatori

purchasePriceUSDnumber

Prezzo di acquisto in USD

Esempio: 350000

downPaymentPercentagenumber

Percentuale di acconto (0-40)

Esempio: 20

interestRatePercentagenumber

Percentuale del tasso d'interesse (0-15)

Esempio: 5.1

mortgageLengthnumber

Durata del mutuo in anni (0-30)

Esempio: 30

yearsRemainingOnMortgagenumber

Anni rimanenti sul mutuo (Non può essere superiore alla durata del mutuo)

bedroomsnumber

Numero di camere da letto

Esempio: 3

bathroomsnumber

Numero di bagni

Esempio: 2

accomodatesnumber

Numero di ospiti che la proprietà può accogliere

Esempio: 6

Parametri Opzionali

monthlyRentUSDnumber

Affitto mensile previsto in USD per un affitto a lungo termine

Esempio: 2500

squareFeetnumber

Superficie in piedi quadrati della proprietà

Esempio: 1500

statestring

Nome dello stato

Esempio: Florida

citystring

Nome della città

Esempio: St. Petersburg

countystring

Nome della contea

Esempio: Pinellas County

postalCodestring

Codice postale

Esempio: 33703

countrystring

Nome del paese

Esempio: United States

streetstring

Nome della strada

Esempio: 2nd Avenue North

streetNumberstring

Numero civico

Esempio: 4935

unitstring

Numero dell'unità o dell'appartamento, se applicabile

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.

Esempio: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

Risposta di esempio

{
  "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

Crea analisi Cohost

Crea la cronologia dei cohost

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumber

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)

Esempio: 27.7676

lngnumber

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)

Esempio: -82.6403

fullAddressstring

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)

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

Parametri Obbligatori

bedroomsnumber

Numero di camere da letto

Esempio: 3

bathroomsnumber

Numero di bagni

Esempio: 2

accomodatesnumber

Numero di ospiti che la proprietà può accogliere

Esempio: 6

Parametri Opzionali

cohostCommissionPercentagenumber

Percentuale della commissione del co-host

Esempio: 10

squareFeetnumber

Superficie in piedi quadrati della proprietà

Esempio: 1500

statestring

Nome dello stato

Esempio: Florida

citystring

Nome della città

Esempio: St. Petersburg

countystring

Nome della contea

Esempio: Pinellas County

postalCodestring

Codice postale

Esempio: 33703

countrystring

Nome del paese

Esempio: United States

streetstring

Nome della strada

Esempio: 2nd Avenue North

streetNumberstring

Numero civico

Esempio: 4935

unitstring

Numero dell'unità o dell'appartamento, se applicabile

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.

Esempio: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

Risposta di esempio

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

Arricchimento IA

POST /v1/external/analysis/enhance

Migliora l'analisi con l'IA

Esegue l'arricchimento AI su un'analisi già creata e restituisce l'analisi ricalcolata. Usalo quando desideri che vengano applicati comparabili selezionati dall'IA o stime di spesa AI a posteriori, o quando preferisci che la chiamata di creazione originale sia veloce.

Strumento MCPenhance_analysis
  • 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.
  • Quando un passaggio IA non può essere completato, la risposta restituisce comunque 201 con l'analisi valida e un array di avvisi che spiega cosa è stato saltato. Controlla gli avvisi invece di presumere che i risultati dell'IA siano sempre presenti.
  • Ogni passaggio AI completato aggiunge $0.10 alla chiamata. I passaggi AI che falliscono o scadono non vengono mai addebitati e /enhance viene fatturato solo per i passaggi AI completati, senza costi di base per chiamata.
  • Se ogni passaggio AI richiesto fallisce, la chiamata è gratuita e la risposta contiene solo avvisi, senza dati. La tua analisi memorizzata rimane invariata in quel caso, quindi la copia che hai già è ancora attuale. Gli endpoint di creazione restituiscono sempre dati, poiché la loro tariffa di base copre il report stesso.

Parametri Obbligatori

analysisIdstring

The _id of an analysis previously created with your API key

Esempio: 000000000000000000000000

Parametri Opzionali

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.

Esempio: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

Risposta di esempio

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

Comportamento dell'arricchimento AI

L'arricchimento AI è opzionale per richiesta tramite addAIComps e addAIExpenseEstimates, e ogni passaggio AI ha un limite di tempo e fallisce apertamente. Una richiesta che ha richiesto l'AI restituisce comunque 201 con un'analisi completa e completamente ricalcolata; tutto ciò che non è stato eseguito viene segnalato nell'array di avvisi di primo livello invece di generare un errore.

Timeout e limiti di richiesta

  • Il lavoro dell'IA ha un budget di 90 secondi misurato dall'inizio della richiesta, non dal momento in cui inizia il passaggio dell'IA, quindi la geocodifica e la creazione dell'analisi contano per esso. Quando il budget si esaurisce, l'analisi viene restituita senza il passaggio IA incompiuto e un avviso di timeout.
  • Imposta il timeout del client ad almeno 300 secondi. La maggior parte delle chiamate AI rientra comodamente nel budget, ma un client che interrompe prima della scadenza del server trasforma un'analisi completata e fatturabile in una risposta persa.
  • Una chiamata al modello richiede almeno 45 secondi di budget residuo per partire. Una richiesta che utilizza la maggior parte del budget aspettando le foto dell'annuncio restituisce ai_comps_timed_out senza chiamare il modello, invece di avviare un'esecuzione che non potrebbe completare.
  • Le richieste che impostano un flag AI sono soggette a limiti per API key: 10 al minuto, con al massimo 2 in volo contemporaneamente. Superare uno di questi limiti restituisce 429 con l'header Retry-After, e le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset sono impostate su ogni richiesta AI. Le chiamate senza flag AI non sono interessate da questo limite.
  • Per riprovare un passaggio IA saltato, chiama POST /v1/external/analysis/enhance con lo stesso analysisId invece di creare nuovamente l'analisi. Enhance non comporta costi di chiamata base, quindi un nuovo tentativo costa solo i passaggi IA che vengono completati.

Avvisi di risposta

Una risposta 201 può ancora contenere un array di avvisi. Trattalo come il registro di ciò che non è stato eseguito e controllalo prima di presumere che i risultati dell'IA siano presenti. Ogni passaggio segnalato qui è stato saltato e i passaggi saltati non vengono mai fatturati.

ai_comps_requires_user_scoped_api_key
AI comps richiedono una API key vincolata a un account utente. La chiave non è stata risolta in un proprietario, quindi il selettore dei comparabili non è mai stato eseguito.
ai_comps_unavailable_for_property
Gli AI comps sono disponibili solo per proprietà negli Stati Uniti, e l'analisi memorizzata è al di fuori di tale ambito.
ai_comps_photos_not_ready
Le foto utilizzabili degli annunci per l'indirizzo non erano pronte in tempo: non ne sono state trovate, troppo poche erano utilizzabili o la galleria era ancora in elaborazione quando il budget si è esaurito. Le foto vengono raccolte in background dopo la creazione di un'analisi, quindi riprovare con /enhance poco dopo di solito ha successo.
ai_comps_timed_out
Il budget AI è terminato prima che il modello rispondesse, quindi sono stati mantenuti i comparabili deterministici e la proiezione dei ricavi.
ai_comps_benchmark_fallback
Il modello è stato eseguito ma ha selezionato troppi pochi comparabili per formare un benchmark, quindi è stata mantenuta la proiezione dei ricavi esistente. Nulla è stato scritto nell'analisi e il passaggio non è stato addebitato.
ai_comps_model_unavailable
Il provider del modello non era disponibile. Questo è transitorio, quindi riprova con /enhance.
ai_comps_already_applied
Questa analisi ha già un benchmark IA valido, quindi non è stato rieseguito né addebitato nulla. Modificare l'immobile lo invalida e la chiamata successiva viene eseguita davvero.
ai_comps_run_in_progress
Un'altra esecuzione AI di comparabili sta già lavorando su questa analisi. Attendi prima di riprovare: l'esecuzione mantiene un blocco per un massimo di 10 minuti.
ai_comps_analysis_changed
L'analisi è stata modificata mentre il modello era in esecuzione, quindi il benchmark non è stato scritto invece di sovrascrivere i valori più recenti. Riprova con /enhance.
ai_comps_forbidden
L'analisi non è stata creata con questa chiave API, quindi gli AI comps non hanno potuto essere eseguiti su di essa.
ai_comps_failed
Gli AI comps non sono potuti essere completati per un'altra ragione. L'analisi stessa è valida e invariata.
ai_expense_estimates_timed_out
Il budget AI è terminato prima che l'estimatore delle spese rispondesse, quindi sono state mantenute le spese operative predefinite.
ai_expense_estimates_no_proposals
L'estimatore non ha prodotto proposte di spesa per questa proprietà, quindi nessuna spesa operativa è stata modificata.
ai_expense_estimates_stale_preview
L'analisi è cambiata mentre la stima veniva preparata, quindi è stata scartata invece di essere applicata a input obsoleti. Riprovare con /enhance.
ai_expense_estimates_model_unavailable
Il provider del modello non era disponibile. Questo è transitorio, quindi riprova con /enhance.
ai_expense_estimates_already_applied
Questa analisi ha già spese stimate dall'IA, quindi non è stato rieseguito né addebitato nulla.
ai_expense_estimates_unavailable_for_property
Nessun campo di spese operative di questa analisi era idoneo alla stima con IA, quindi sono state mantenute le spese predefinite.
ai_expense_estimates_forbidden
L'analisi non è stata creata con questa chiave API, quindi le stime delle spese con IA non hanno potuto essere eseguite su di essa.
ai_expense_estimates_failed
Le stime delle spese AI non sono potute essere applicate. L'analisi mantiene le sue spese operative predefinite.

Match sui prefissi ai_comps_ e ai_expense_estimates_ piuttosto che sulla stringa esatta: qualsiasi altro codice con quei prefissi significa che quel passaggio è fallito, non è stato applicato e non è stato addebitato.

Risposta di esempio

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

aiComps.warnings

L'array annidato aiComps.warnings è un segnale diverso da quello di primo livello: descrive la qualità del pool di comparabili con cui il modello ha lavorato, non un passaggio che è fallito. Leggi aiComps.applied per sapere se il benchmark AI è stato effettivamente scritto nell'analisi.

thin_benchmark_pool
Meno di quattro comparabili hanno supportato il benchmark, quindi si basa su un campione ridotto.
no_benchmark_comps
Nessun comparabile ha superato la selezione. Il benchmark è vuoto e la proiezione dei ricavi è rimasta invariata.
ai_benchmark_fallback_to_projected_revenue
Sono stati selezionati meno di tre comparabili, quindi è stata mantenuta la proiezione dei ricavi esistente invece del benchmark AI. Questo è lo stesso esito segnalato come ai_comps_benchmark_fallback a livello superiore.
minimum_benchmark_pool_backfill
Il pool del benchmark è stato integrato con comparabili che il modello non aveva scelto per raggiungere il conteggio minimo.

Fatturazione quando l'AI è parziale

Ogni passaggio AI completato aggiunge $0.10 alla chiamata. I passaggi che scadono, falliscono o tornano alla proiezione esistente non vengono addebitati (aiComps.applied impostato su false significa che i confronti AI non sono stati addebitati) e una chiamata /enhance in cui ogni passaggio richiesto è stato saltato non viene addebitata affatto.

Limiti di frequenza

I limiti contano per IP del chiamante, a meno che una riga non dica diversamente. Le risposte limitate riportano X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una richiesta oltre un limite restituisce 429 con un header Retry-After in secondi e non viene mai fatturata, quindi attendere quel lasso di tempo prima di riprovare.

100 al secondo
Ogni route /v1/external.
5 al minuto
POST /v1/external/analysis/enhance ed esecuzioni di Listing Optimizer (run_listing_optimization).
10 al minuto
Richieste che impostano addAIComps o addAIExpenseEstimates, per chiave API, con al massimo 2 in corso.
Da 10 a 60 al minuto
Annunci live 10; dettagli dell'immobile, stime di affitto e account 30; ore di partecipazione materiale di registrazione 60.
2.000 al giorno
Ricerche dati (stime di fatturato, tariffe notturne, comparabili, annunci e foto, annunci live, dettagli immobiliari e stime di affitto) per account, condivise dall'API REST e dal server MCP, e fino a 2.500 righe di annunci al giorno. Il limite viene reimpostato alle 00:00 UTC.

Codici di errore

L'API di BNBCalc usa i codici di stato HTTP standard per indicare il successo o il fallimento delle richieste. Le richieste riuscite restituiscono codici 2xx, mentre gli errori restituiscono codici 4xx o 5xx con informazioni aggiuntive nel corpo della risposta. Le richieste non riuscite (4xx o 5xx) non vengono mai addebitate.

201
Creato: l'analisi è stata creata o migliorata e si trova nella risposta
400
Richiesta errata - Parametri non validi
401
Non autorizzato - Chiave API non valida
402
Payment Required - L'account della chiave non ha un abbonamento API attivo o non ha più crediti Listing Optimizer
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - L'analisi, l'annuncio o la località richiesti non sono stati trovati
409
Conflict - È già in corso un'esecuzione IA o di Listing Optimizer, l'analisi è cambiata da quando l'hai letta o il report non è ancora pronto
429
Troppe richieste - limite superato per la rotta API esterna
500
Errore interno del server
502
Bad Gateway - The AI model returned an unusable response
503
Service Unavailable - Un modello IA o la fonte degli annunci non è temporaneamente disponibile; riprova più tardi
Verifica lo stato dell'API

Guide API

Prezzi API

Scopri quanto costa l'API di BNBCalc: $0 al mese, $0.20 per report e $0.10 per ogni passaggio di IA completato.

Casi d'uso API

Vedi come le piattaforme PropTech, gli investitori, i finanziatori, gli operatori e gli analisti utilizzano l'API nei flussi di lavoro di produzione.

Copertura dei dati

Comprendi la copertura delle proprietà internazionali, le stime basate su comparabili, gli input di localizzazione e dove si inserisce l'API.

Confronto API

Vedi come l'API BNBCalc si confronta con l'API di AirDNA e altre API di dati di Airbnb per accesso, modello di prezzo e output.

Fogli Google

Analizza un elenco di indirizzi in Fogli Google con un breve Apps Script.

Server MCP

Collega Claude, Cursor o VS Code a BNBCalc ed esegui stime sui ricavi e analisi delle operazioni dal tuo assistente AI.

Guida alla configurazione MCP

Collega Claude, ChatGPT, Claude Code, Cursor o VS Code al server MCP, passo dopo passo.

Riferimento MCP

Come il server MCP esegue l'autenticazione, ogni strumento con il suo prezzo, l'approvazione degli strumenti a pagamento e i limiti.

Registro delle modifiche

Cosa è cambiato nell'API REST e nel server MCP, in ordine cronologico.

Stato

Controlli live dell'API REST e del server MCP.