Documentazione API dei dati di Airbnb

Benvenuto nell'API BNBCalc. Questa documentazione ti aiuta a integrare l'analisi delle proprietà di affitto a breve termine nella tua applicazione.

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.

Primi passi

Per iniziare a utilizzare l'API dei dati di Airbnb BNBCalc, dovrai:

1. Crea un account BNBCalc oppure accedi al tuo account esistente

2. Vai alle impostazioni del tuo account per generare una chiave API

3. Includi la tua chiave API in tutte le richieste API utilizzando l'intestazione x-bnbcalc-api-key.

4. Inizia a fare richieste per accedere ai dati e alle analisi degli immobili.

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.

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:

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.

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.

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.

Parametri di Posizione (Condizionali)

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

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

purchasePriceUSDnumberrichiesto

Prezzo di acquisto in USD(e.g., 350000)

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

monthlyRentUSDnumberopzionale

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

interestRatePercentagenumberopzionale

Percentuale del tasso d'interesse (0-15)(e.g., 5.1)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

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

addAICompsbooleanopzionale

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)

addAIExpenseEstimatesbooleanopzionale

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

Richiesta di esempio

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()

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

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.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

monthlyRentUSDnumberrichiesto

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

purchasePriceUSDnumberopzionale

Prezzo di acquisto in USD(e.g., 350000)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

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

addAICompsbooleanopzionale

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)

addAIExpenseEstimatesbooleanopzionale

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

Richiesta di esempio

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()

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.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

purchasePriceUSDnumberrichiesto

Prezzo di acquisto in USD(e.g., 350000)

downPaymentPercentagenumberrichiesto

Percentuale di acconto (0-40)(e.g., 20)

interestRatePercentagenumberrichiesto

Percentuale del tasso d'interesse (0-15)(e.g., 5.1)

mortgageLengthnumberrichiesto

Durata del mutuo in anni (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberrichiesto

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

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

monthlyRentUSDnumberopzionale

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

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

addAICompsbooleanopzionale

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)

addAIExpenseEstimatesbooleanopzionale

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

Richiesta di esempio

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()

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

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.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

cohostCommissionPercentagenumberopzionale

Percentuale della commissione del co-host(e.g., 10)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

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

addAICompsbooleanopzionale

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)

addAIExpenseEstimatesbooleanopzionale

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

Richiesta di esempio

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()

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

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.

Se tutte le funzioni IA richieste falliscono, la chiamata è gratuita e la risposta contiene solo warnings, senza data. In quel caso la tua analisi memorizzata resta invariata, quindi la copia che hai già è ancora aggiornata. Gli endpoint di creazione restituiscono sempre data, perché la loro tariffa base copre il report stesso.

Parametri Obbligatori

analysisIdstringrichiesto

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

Parametri Opzionali

addAICompsbooleanopzionale

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)

addAIExpenseEstimatesbooleanopzionale

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

Richiesta di esempio

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()

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 è limitato nel tempo e in caso di errore fallisce aperto. Una richiesta che richiede AI restituisce comunque 200 con un'analisi completa e completamente ricalcolata; tutto ciò che non è stato eseguito viene segnalato nell'array warnings di primo livello invece di generare un errore.

Timeout e limiti di richiesta

Il lavoro AI ha un budget di 90 secondi misurato dall'inizio della richiesta, non dal momento in cui inizia il passaggio AI — geocoding e creazione dell'analisi sono conteggiati nel budget. Quando il budget scade, l'analisi viene restituita senza il passaggio AI non terminato e con 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 AI saltato, chiama POST /v1/external/analysis/enhance con lo stesso analysisId invece di creare nuovamente l'analisi. /enhance non comporta una tariffa base per chiamata, quindi un retry costa solo le funzioni AI che vengono completate.

Avvisi di risposta

Una risposta 200 può comunque contenere un array warnings. Trattalo come il registro di ciò che non è stato eseguito e controllalo prima di presumere che i risultati AI 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 dell'annuncio utilizzabili per l'indirizzo non erano pronte in tempo — non ne sono state trovate, erano troppo poche utilizzabili, o la galleria era ancora in elaborazione quando il budget è terminato. 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. Si tratta di un problema transitorio — riprovare 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 di AI comps sta già lavorando su questa analisi. Attendi prima di riprovare: l'esecuzione mantiene un blocco fino a 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. Si tratta di un problema transitorio — riprovare 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 funzione AI che viene completata aggiunge $0.10 alla chiamata. I passaggi che scadono per timeout, falliscono o ricorrono alla proiezione esistente non vengono addebitati — aiComps.applied impostato a false significa che gli AI comps non sono stati fatturati — e una chiamata /enhance in cui ogni passaggio richiesto è stato saltato non viene fatturata affatto.

Codici di errore

L'API BNBCalc utilizza codici di stato di risposta HTTP standard per indicare il successo o il fallimento delle richieste API. I report creati con successo restituiscono codici 2xx, mentre gli errori restituiscono codici 4xx o 5xx con ulteriori informazioni sugli errori nel corpo della risposta. Sarai addebitato solo per i report creati con successo.

200

Successo

400

Richiesta errata - Parametri non validi

401

Non autorizzato - Chiave API non valida

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

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