Airbnb-Daten-API-Dokumentation

Willkommen bei der BNBCalc API. Diese Dokumentation hilft Ihnen, die Analyse von Kurzzeitvermietungsimmobilien in Ihre Anwendung zu integrieren.

Verwenden Sie die BNBCalc Airbnb-Daten-API, um Immobilien Einnahmen, Belegung, ADR, aktive Airbnb vergleichbare Listen, Perzentile, Investitionskennzahlen und gehostete Bericht-URLs für Apps, Berichte, Underwriting und Management-Tools zu erhalten.

Erste Schritte

Um die BNBCalc Airbnb-Daten-API zu nutzen, müssen Sie:

1. Erstelle ein BNBCalc-Konto oder melde dich bei deinem bestehenden Konto an

2. Navigieren Sie zu Ihren Kontoeinstellungen, um einen API-Schlüssel zu generieren

3. Fügen Sie Ihren API-Schlüssel in allen API-Anfragen mit dem Header x-bnbcalc-api-key ein.

4. Beginnen Sie damit, Anfragen zu stellen, um auf Immobiliendaten und Analysen zuzugreifen.

Alle API-Endpunkte verwenden HTTPS und geben JSON-Antworten zurück. Bewahren Sie API-Schlüssel auf Ihrem Server auf, nicht im Code Ihres Browsers oder mobilen Clients. Externe API-Routen sind derzeit auf 100 Anfragen pro Sekunde beschränkt und verwenden die standardmäßigen HTTP-Antwortcodes, um Erfolg oder Misserfolg anzuzeigen.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel. API-Schlüssel sind mit Ihrem BNBCalc-Konto verknüpft, sollten serverseitig gespeichert und niemals im Frontend-Code offengelegt werden. Fügen Sie Ihren API-Schlüssel in den Anfrage-Header wie unten gezeigt ein:

x-bnbcalc-api-key: YOUR_API_KEY

Sie können API-Schlüssel selbstständig auf Ihrer Kontoeinstellungsseite generieren. Fügen Sie den x-bnbcalc-api-key-Header in jede API-Anfrage ein, um sich zu authentifizieren.

POST/v1/external/analysis/create/buy

Kaufanalyse erstellen

Erstellen Sie eine neue Kaufanalyse für eine Immobilie. Erfordert Immobiliendetails, Standortinformationen und Kaufpreis.

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.

Standortparameter (Bedingt)

⚠️ Geben Sie entweder lat UND lng an ODER geben Sie fullAddress an. Mindestens eine Methode ist erforderlich.

latnumberbedingt

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., 27.7676)

lngnumberbedingt

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., -82.6403)

fullAddressstringbedingt

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Erforderliche Parameter

purchasePriceUSDnumbererforderlich

Kaufpreis in USD(e.g., 350000)

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

Anzahl der Gäste, die die Immobilie aufnehmen kann(e.g., 6)

Optionale Parameter

monthlyRentUSDnumberoptionaler Parameter

Erwartete monatliche Miete in USD für langfristige Vermietung(e.g., 2500)

interestRatePercentagenumberoptionaler Parameter

Zinssatz in Prozent (0-15)(e.g., 5.1)

squareFeetnumberoptionaler Parameter

Quadratfußzahl der Immobilie(e.g., 1500)

statestringoptionaler Parameter

Name des Staates(e.g., Florida)

citystringoptionaler Parameter

Stadtname(e.g., St. Petersburg)

countystringoptionaler Parameter

Name des Landkreises(e.g., Pinellas County)

postalCodestringoptionaler Parameter

Postleitzahl(e.g., 33703)

countrystringoptionaler Parameter

Name des Landes(e.g., United States)

streetstringoptionaler Parameter

Straßenname(e.g., 2nd Avenue North)

streetNumberstringoptionaler Parameter

Hausnummer(e.g., 4935)

unitstringoptionaler Parameter

Wohnungs-/Einheitsnummer, falls zutreffend

addAICompsbooleanoptionaler Parameter

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)

addAIExpenseEstimatesbooleanoptionaler Parameter

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

Beispielanfrage

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

Beispielantwort

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

Arbitrage-Analyse erstellen

Erstelle eine neue Arbitrage-Analyse (Mietarbitrage) für eine Immobilie. Verwendet dieselben erforderlichen Felder wie bei der Kaufanalyse.

Standortparameter (Bedingt)

⚠️ Geben Sie entweder lat UND lng an ODER geben Sie fullAddress an. Mindestens eine Methode ist erforderlich.

latnumberbedingt

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., 27.7676)

lngnumberbedingt

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., -82.6403)

fullAddressstringbedingt

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Erforderliche Parameter

monthlyRentUSDnumbererforderlich

Erwartete monatliche Miete in USD für langfristige Vermietung(e.g., 2500)

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

Anzahl der Gäste, die die Immobilie aufnehmen kann(e.g., 6)

Optionale Parameter

purchasePriceUSDnumberoptionaler Parameter

Kaufpreis in USD(e.g., 350000)

squareFeetnumberoptionaler Parameter

Quadratfußzahl der Immobilie(e.g., 1500)

statestringoptionaler Parameter

Name des Staates(e.g., Florida)

citystringoptionaler Parameter

Stadtname(e.g., St. Petersburg)

countystringoptionaler Parameter

Name des Landkreises(e.g., Pinellas County)

postalCodestringoptionaler Parameter

Postleitzahl(e.g., 33703)

countrystringoptionaler Parameter

Name des Landes(e.g., United States)

streetstringoptionaler Parameter

Straßenname(e.g., 2nd Avenue North)

streetNumberstringoptionaler Parameter

Hausnummer(e.g., 4935)

unitstringoptionaler Parameter

Wohnungs-/Einheitsnummer, falls zutreffend

addAICompsbooleanoptionaler Parameter

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)

addAIExpenseEstimatesbooleanoptionaler Parameter

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

Beispielanfrage

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

Beispielantwort

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

Eigene Analyse erstellen

Erstellen Sie eine neue Analyse für eine Immobilie im Eigentum. Verwendet die gleichen erforderlichen Felder wie die Kaufanalyse.

Standortparameter (Bedingt)

⚠️ Geben Sie entweder lat UND lng an ODER geben Sie fullAddress an. Mindestens eine Methode ist erforderlich.

latnumberbedingt

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., 27.7676)

lngnumberbedingt

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., -82.6403)

fullAddressstringbedingt

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Erforderliche Parameter

purchasePriceUSDnumbererforderlich

Kaufpreis in USD(e.g., 350000)

downPaymentPercentagenumbererforderlich

Anzahlungsprozentsatz (0-40)(e.g., 20)

interestRatePercentagenumbererforderlich

Zinssatz in Prozent (0-15)(e.g., 5.1)

mortgageLengthnumbererforderlich

Hypothekenlaufzeit in Jahren (0-30)(e.g., 30)

yearsRemainingOnMortgagenumbererforderlich

Verbleibende Jahre der Hypothek (Dürfen nicht länger sein als die Hypothekendauer)

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

Anzahl der Gäste, die die Immobilie aufnehmen kann(e.g., 6)

Optionale Parameter

monthlyRentUSDnumberoptionaler Parameter

Erwartete monatliche Miete in USD für langfristige Vermietung(e.g., 2500)

squareFeetnumberoptionaler Parameter

Quadratfußzahl der Immobilie(e.g., 1500)

statestringoptionaler Parameter

Name des Staates(e.g., Florida)

citystringoptionaler Parameter

Stadtname(e.g., St. Petersburg)

countystringoptionaler Parameter

Name des Landkreises(e.g., Pinellas County)

postalCodestringoptionaler Parameter

Postleitzahl(e.g., 33703)

countrystringoptionaler Parameter

Name des Landes(e.g., United States)

streetstringoptionaler Parameter

Straßenname(e.g., 2nd Avenue North)

streetNumberstringoptionaler Parameter

Hausnummer(e.g., 4935)

unitstringoptionaler Parameter

Wohnungs-/Einheitsnummer, falls zutreffend

addAICompsbooleanoptionaler Parameter

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)

addAIExpenseEstimatesbooleanoptionaler Parameter

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

Beispielanfrage

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

Beispielantwort

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

Cohost-Analyse erstellen

Co-Host-Historie erstellen

Standortparameter (Bedingt)

⚠️ Geben Sie entweder lat UND lng an ODER geben Sie fullAddress an. Mindestens eine Methode ist erforderlich.

latnumberbedingt

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., 27.7676)

lngnumberbedingt

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)(e.g., -82.6403)

fullAddressstringbedingt

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Erforderliche Parameter

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

Anzahl der Gäste, die die Immobilie aufnehmen kann(e.g., 6)

Optionale Parameter

cohostCommissionPercentagenumberoptionaler Parameter

Cohost-Provisionsprozentsatz(e.g., 10)

squareFeetnumberoptionaler Parameter

Quadratfußzahl der Immobilie(e.g., 1500)

statestringoptionaler Parameter

Name des Staates(e.g., Florida)

citystringoptionaler Parameter

Stadtname(e.g., St. Petersburg)

countystringoptionaler Parameter

Name des Landkreises(e.g., Pinellas County)

postalCodestringoptionaler Parameter

Postleitzahl(e.g., 33703)

countrystringoptionaler Parameter

Name des Landes(e.g., United States)

streetstringoptionaler Parameter

Straßenname(e.g., 2nd Avenue North)

streetNumberstringoptionaler Parameter

Hausnummer(e.g., 4935)

unitstringoptionaler Parameter

Wohnungs-/Einheitsnummer, falls zutreffend

addAICompsbooleanoptionaler Parameter

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)

addAIExpenseEstimatesbooleanoptionaler Parameter

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

Beispielanfrage

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

Beispielantwort

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

Schlagen alle angeforderten KI-Funktionen fehl, ist der Aufruf kostenlos und die Antwort enthält nur warnings — kein data. Ihre gespeicherte Analyse bleibt dann unverändert, die Kopie, die Sie bereits haben, ist also weiterhin aktuell. Create-Endpunkte liefern immer data, da ihre Grundgebühr den Bericht selbst abdeckt.

Erforderliche Parameter

analysisIdstringerforderlich

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

Optionale Parameter

addAICompsbooleanoptionaler Parameter

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)

addAIExpenseEstimatesbooleanoptionaler Parameter

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

Beispielanfrage

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

Beispielantwort

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

Verhalten der AI-Anreicherung

Die AI-Anreicherung ist pro Anfrage optional — sie wird über addAIComps und addAIExpenseEstimates aktiviert — und jeder AI‑Schritt ist zeitlich begrenzt und bricht nicht den gesamten Request ab. Eine Anfrage, die AI angefordert hat, liefert weiterhin einen 200-Status mit einer vollständigen, neu berechneten Analyse; alles, was nicht ausgeführt werden konnte, wird stattdessen im warnings‑Array auf oberster Ebene gemeldet, anstatt einen Fehler zu werfen.

Timeouts und Rate-Limits

Für AI-Arbeit steht ein Budget von 90 Sekunden zur Verfügung, gerechnet ab Beginn der Anfrage, nicht ab dem Start des AI‑Schritts — Geokodierung und Erstellung der Analyse zählen dazu. Wenn das Budget erschöpft ist, wird die Analyse ohne den nicht abgeschlossenen AI‑Schritt zurückgegeben und eine Timeout‑Warnung ausgegeben.

Stellen Sie Ihren Client‑Timeout auf mindestens 300 Sekunden ein. Die meisten AI‑Aufrufe beenden sich deutlich innerhalb des Budgets, aber ein Client, der früher als die Server‑Deadline abbricht, verwandelt eine abrechenbare, abgeschlossene Analyse in eine verlorene Antwort.

Ein Modellaufruf benötigt mindestens 45 Sekunden Restbudget, um zu beginnen. Eine Anfrage, die den Großteil ihres Budgets damit verbringt, auf Listing‑Fotos zu warten, gibt ai_comps_timed_out zurück, ohne das Modell zu starten, anstatt einen Lauf zu beginnen, den es nicht beenden kann.

Anfragen mit gesetztem AI‑Flag werden pro API‑Schlüssel rate‑limitiert: 10 pro Minute, maximal 2 gleichzeitig laufend. Das Überschreiten einer der Grenzen liefert einen 429 mit einem Retry-After‑Header, und X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset werden bei jeder AI‑Anfrage gesetzt. Aufrufe ohne AI‑Flag sind von diesem Limit nicht betroffen.

Um einen übersprungenen AI‑Schritt erneut zu versuchen, rufen Sie POST /v1/external/analysis/enhance mit derselben analysisId auf, statt die Analyse neu zu erstellen. Enhance hat keine Grundgebühr pro Aufruf, sodass ein Retry nur die erfolgreich abgeschlossenen AI‑Funktionen kostet.

Warnungen in der Antwort

Eine 200‑Antwort kann dennoch ein warnings‑Array enthalten. Betrachten Sie es als Aufzeichnung dessen, was nicht ausgeführt wurde, und prüfen Sie es, bevor Sie davon ausgehen, dass AI‑Ergebnisse vorliegen. Jeder hier gemeldete Schritt wurde übersprungen, und übersprungene Schritte werden niemals berechnet.

ai_comps_requires_user_scoped_api_key

Für AI‑Comps ist ein an ein Benutzerkonto gebundener API‑Schlüssel erforderlich. Der Schlüssel konnte keinem Besitzer zugeordnet werden, daher lief der Comp‑Selektor nie.

ai_comps_unavailable_for_property

AI‑Comps sind nur für Objekte in den Vereinigten Staaten verfügbar, und die gespeicherte Analyse liegt außerhalb dieses Geltungsbereichs.

ai_comps_photos_not_ready

Verwendbare Listing‑Fotos zur Adresse waren nicht rechtzeitig verfügbar — es wurden keine gefunden, zu wenige waren nutzbar, oder die Galerie wurde noch verarbeitet, als das Budget auslief. Fotos werden nach Erstellung einer Analyse im Hintergrund gesammelt, daher gelingt ein erneuter Versuch mit /enhance kurz danach normalerweise.

ai_comps_timed_out

Das AI‑Budget lief ab, bevor das Modell antwortete, daher wurden die deterministischen Vergleichsobjekte und die Umsatzprognose beibehalten.

ai_comps_benchmark_fallback

Das Modell lief zwar, wählte aber zu wenige Vergleichsobjekte, um einen Benchmark zu bilden, daher blieb die bestehende Umsatzprognose erhalten. Es wurde nichts in die Analyse geschrieben und der Schritt wurde nicht berechnet.

ai_comps_model_unavailable

Der Modellanbieter war nicht verfügbar. Dies ist vorübergehend — versuchen Sie es erneut mit /enhance.

ai_comps_already_applied

Diese Analyse hat bereits einen gültigen KI-Benchmark, daher wurde nichts erneut ausgeführt und nichts berechnet. Eine Bearbeitung der Immobilie macht ihn ungültig, und der nächste Aufruf läuft echt.

ai_comps_run_in_progress

Ein anderer AI-Comps-Lauf bearbeitet diese Analyse bereits. Warten Sie vor einem erneuten Versuch — der Lauf hält bis zu 10 Minuten eine Sperre.

ai_comps_analysis_changed

Die Analyse wurde während des Modelllaufs bearbeitet, daher wurde der Benchmark nicht geschrieben, statt die neueren Werte zu überschreiben. Erneut mit /enhance versuchen.

ai_comps_forbidden

Die Analyse wurde nicht mit diesem API-Schlüssel erstellt, daher konnten AI-Comps nicht darauf ausgeführt werden.

ai_comps_failed

AI‑Comps konnten aus einem anderen Grund nicht abgeschlossen werden. Die Analyse selbst ist gültig und unverändert.

ai_expense_estimates_timed_out

Das AI‑Budget lief ab, bevor der Kostenabschätzer antwortete, daher blieben die Standard‑Betriebskosten erhalten.

ai_expense_estimates_no_proposals

Der Schätzer lieferte keine Kosten‑Vorschläge für diese Immobilie, daher wurde keine Betriebskostenposition geändert.

ai_expense_estimates_stale_preview

Die Analyse änderte sich, während die Schätzung vorbereitet wurde, daher wurde sie verworfen, statt auf veraltete Eingaben angewendet zu werden. Versuchen Sie /enhance erneut.

ai_expense_estimates_model_unavailable

Der Modellanbieter war nicht verfügbar. Dies ist vorübergehend — versuchen Sie es erneut mit /enhance.

ai_expense_estimates_already_applied

Diese Analyse hat bereits KI-geschätzte Kosten, daher wurde nichts erneut ausgeführt und nichts berechnet.

ai_expense_estimates_unavailable_for_property

Kein Betriebskostenfeld dieser Analyse war für eine KI-Schätzung geeignet, daher wurden die Standardkosten beibehalten.

ai_expense_estimates_forbidden

Die Analyse wurde nicht mit diesem API-Schlüssel erstellt, daher konnten KI-Kostenschätzungen nicht darauf ausgeführt werden.

ai_expense_estimates_failed

AI‑Kostenabschätzungen konnten nicht angewendet werden. Die Analyse behält ihre Standard‑Betriebskosten bei.

Matchen Sie anhand der Präfixe ai_comps_ und ai_expense_estimates_ statt nach dem exakten String: Jeder andere Code mit diesen Präfixen bedeutet, dass der Schritt fehlgeschlagen ist, nicht angewendet wurde und nicht berechnet wurde.

Beispielantwort

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

aiComps.warnings

Das verschachtelte aiComps.warnings‑Array ist ein anderer Hinweis als das oberste: Es beschreibt die Qualität des Vergleichspools, mit dem das Modell gearbeitet hat, nicht einen fehlgeschlagenen Schritt. Lesen Sie aiComps.applied, um zu erfahren, ob der AI‑Benchmark tatsächlich in die Analyse geschrieben wurde.

thin_benchmark_pool

Weniger als vier Vergleichsobjekte stützten den Benchmark, sodass er auf einer kleinen Stichprobe beruht.

no_benchmark_comps

Kein Vergleichsobjekt bestand die Auswahl. Der Benchmark ist leer und die Umsatzprognose blieb unverändert.

ai_benchmark_fallback_to_projected_revenue

Weniger als drei Vergleichsobjekte wurden ausgewählt, daher wurde die bestehende Umsatzprognose statt des AI‑Benchmarks beibehalten. Dies ist dasselbe Ergebnis, das oben als ai_comps_benchmark_fallback gemeldet wird.

minimum_benchmark_pool_backfill

Der Benchmark‑Pool wurde mit Vergleichsobjekten aufgefüllt, die das Modell nicht gewählt hatte, um die Mindestanzahl zu erreichen.

Abrechnung bei teilweiser AI‑Nutzung

Jede abgeschlossene AI‑Funktion erhöht die Kosten des Aufrufs um $0.10. Schritte, die zeitlich auslaufen, fehlschlagen oder auf die bestehende Prognose zurückfallen, werden nicht berechnet — aiComps.applied auf false bedeutet, dass AI‑Comps nicht berechnet wurden — und ein /enhance‑Aufruf, bei dem jeder angeforderte Schritt übersprungen wurde, wird überhaupt nicht berechnet.

Fehlercodes

Die BNBCalc API verwendet standardisierte HTTP-Antwortstatuscodes, um den Erfolg oder Misserfolg der API-Anfragen anzuzeigen. Erfolgreich erstellte Berichte geben 2xx-Codes zurück, während Fehler 4xx- oder 5xx-Codes mit zusätzlichen Fehlermeldungen im Antwortkörper zurückgeben. Ihnen werden nur erfolgreiche erstellte Berichte in Rechnung gestellt.

200

Erfolg

400

Fehlerhafte Anfrage - Ungültige Parameter

401

Nicht autorisiert - Ungültiger API-Schlüssel

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

Zu viele Anfragen - Limit der externen API-Routen überschritten

500

Interner Serverfehler

502

Bad Gateway - The AI model returned an unusable response

503

Service Unavailable - The AI model is temporarily unavailable