Airbnb-Daten-API-Dokumentation

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.

OpenAPI-Spezifikation
Basis-URL
https://atlas.bnbcalc.com
API-Schlüssel-Header
x-bnbcalc-api-key
MCP-Server
https://atlas.bnbcalc.com/mcp
Aktualisiert

Erste Schritte

  1. 1

    Erstelle ein BNBCalc-Konto und generiere einen API-Schlüssel in den Dashboard‑Einstellungen.

  2. 2

    Sende deinen Schlüssel in jedem Request im Header x-bnbcalc-api-key.

  3. 3

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

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.

Importieren Sie die OpenAPI 3.1 Beschreibung in Postman, Insomnia oder einen Client-Generator: https://www.bnbcalc.com/developers/openapi.json

Schreiben Sie keinen Code? Nutzen Sie BNBCalc von Claude, ChatGPT oder einer anderen KI-App stattdessen. Anleitungen zur MCP-Einrichtung

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:

HTTP

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.

Analysen erstellen

  • 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.
  • Wenn ein KI-Schritt nicht abgeschlossen werden kann, gibt die Antwort immer noch 201 mit der gültigen Analyse und einem Warnungsarray zurück, das erklärt, was übersprungen wurde. Überprüfen Sie die Warnungen, anstatt davon auszugehen, dass KI-Ergebnisse immer vorhanden sind.
  • Jeder abgeschlossene KI-Schritt fügt dem Aufruf 0,10 $ hinzu. KI-Schritte, die fehlschlagen oder abbrechen, werden nie berechnet, und /enhance wird nur für die erfolgreich abgeschlossenen KI-Schritte berechnet, ohne Grundgebühr für den Aufruf.

POST /v1/external/analysis/create/buy

Kaufanalyse erstellen

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

MCP-Toolcreate_buy_analysis

Standortparameter (Bedingt)

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

latnumber

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: 27.7676

lngnumber

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: -82.6403

fullAddressstring

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)

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

Erforderliche Parameter

purchasePriceUSDnumber

Kaufpreis in USD

Beispiel: 350000

bedroomsnumber

Anzahl der Schlafzimmer

Beispiel: 3

bathroomsnumber

Anzahl der Badezimmer

Beispiel: 2

accomodatesnumber

Anzahl der Gäste, die die Immobilie aufnehmen kann

Beispiel: 6

Optionale Parameter

monthlyRentUSDnumber

Erwartete monatliche Miete in USD für langfristige Vermietung

Beispiel: 2500

interestRatePercentagenumber

Zinssatz in Prozent (0-15)

Beispiel: 5.1

downPaymentPercentagenumber

Anzahlungsprozentsatz (0-40)

Beispiel: 25

mortgageLengthnumber

Hypothekenlaufzeit in Jahren (0-30)

Beispiel: 15

squareFeetnumber

Quadratfußzahl der Immobilie

Beispiel: 1500

statestring

Name des Staates

Beispiel: Florida

citystring

Stadtname

Beispiel: St. Petersburg

countystring

Name des Landkreises

Beispiel: Pinellas County

postalCodestring

Postleitzahl

Beispiel: 33703

countrystring

Name des Landes

Beispiel: United States

streetstring

Straßenname

Beispiel: 2nd Avenue North

streetNumberstring

Hausnummer

Beispiel: 4935

unitstring

Wohnungs-/Einheitsnummer, falls zutreffend

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.

Beispiel: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

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.

latnumber

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: 27.7676

lngnumber

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: -82.6403

fullAddressstring

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)

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

Erforderliche Parameter

monthlyRentUSDnumber

Erwartete monatliche Miete in USD für langfristige Vermietung

Beispiel: 2500

bedroomsnumber

Anzahl der Schlafzimmer

Beispiel: 3

bathroomsnumber

Anzahl der Badezimmer

Beispiel: 2

accomodatesnumber

Anzahl der Gäste, die die Immobilie aufnehmen kann

Beispiel: 6

Optionale Parameter

purchasePriceUSDnumber

Kaufpreis in USD

Beispiel: 350000

squareFeetnumber

Quadratfußzahl der Immobilie

Beispiel: 1500

statestring

Name des Staates

Beispiel: Florida

citystring

Stadtname

Beispiel: St. Petersburg

countystring

Name des Landkreises

Beispiel: Pinellas County

postalCodestring

Postleitzahl

Beispiel: 33703

countrystring

Name des Landes

Beispiel: United States

streetstring

Straßenname

Beispiel: 2nd Avenue North

streetNumberstring

Hausnummer

Beispiel: 4935

unitstring

Wohnungs-/Einheitsnummer, falls zutreffend

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.

Beispiel: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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.

latnumber

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: 27.7676

lngnumber

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: -82.6403

fullAddressstring

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)

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

Erforderliche Parameter

purchasePriceUSDnumber

Kaufpreis in USD

Beispiel: 350000

downPaymentPercentagenumber

Anzahlungsprozentsatz (0-40)

Beispiel: 20

interestRatePercentagenumber

Zinssatz in Prozent (0-15)

Beispiel: 5.1

mortgageLengthnumber

Hypothekenlaufzeit in Jahren (0-30)

Beispiel: 30

yearsRemainingOnMortgagenumber

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

bedroomsnumber

Anzahl der Schlafzimmer

Beispiel: 3

bathroomsnumber

Anzahl der Badezimmer

Beispiel: 2

accomodatesnumber

Anzahl der Gäste, die die Immobilie aufnehmen kann

Beispiel: 6

Optionale Parameter

monthlyRentUSDnumber

Erwartete monatliche Miete in USD für langfristige Vermietung

Beispiel: 2500

squareFeetnumber

Quadratfußzahl der Immobilie

Beispiel: 1500

statestring

Name des Staates

Beispiel: Florida

citystring

Stadtname

Beispiel: St. Petersburg

countystring

Name des Landkreises

Beispiel: Pinellas County

postalCodestring

Postleitzahl

Beispiel: 33703

countrystring

Name des Landes

Beispiel: United States

streetstring

Straßenname

Beispiel: 2nd Avenue North

streetNumberstring

Hausnummer

Beispiel: 4935

unitstring

Wohnungs-/Einheitsnummer, falls zutreffend

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.

Beispiel: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

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.

latnumber

Breitengrad (muss mit lng angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: 27.7676

lngnumber

Längengrad (muss mit lat angegeben werden, wenn fullAddress nicht verwendet wird)

Beispiel: -82.6403

fullAddressstring

Vollständige Immobilienadresse (kann anstelle von lat/lng-Koordinaten verwendet werden)

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

Erforderliche Parameter

bedroomsnumber

Anzahl der Schlafzimmer

Beispiel: 3

bathroomsnumber

Anzahl der Badezimmer

Beispiel: 2

accomodatesnumber

Anzahl der Gäste, die die Immobilie aufnehmen kann

Beispiel: 6

Optionale Parameter

cohostCommissionPercentagenumber

Cohost-Provisionsprozentsatz

Beispiel: 10

squareFeetnumber

Quadratfußzahl der Immobilie

Beispiel: 1500

statestring

Name des Staates

Beispiel: Florida

citystring

Stadtname

Beispiel: St. Petersburg

countystring

Name des Landkreises

Beispiel: Pinellas County

postalCodestring

Postleitzahl

Beispiel: 33703

countrystring

Name des Landes

Beispiel: United States

streetstring

Straßenname

Beispiel: 2nd Avenue North

streetNumberstring

Hausnummer

Beispiel: 4935

unitstring

Wohnungs-/Einheitsnummer, falls zutreffend

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.

Beispiel: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

KI-Anreicherung

POST /v1/external/analysis/enhance

Analyse mit KI erweitern

Führt eine KI-Anreicherung gegen eine bereits erstellte Analyse aus und gibt die neu berechnete Analyse zurück. Verwenden Sie dies, wenn Sie KI-ausgewählte Vergleichsobjekte oder KI-Kostenschätzungen nachträglich anwenden möchten oder wenn Sie den ursprünglichen Erstellungsvorgang schnell halten möchten.

  • 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.
  • Wenn ein KI-Schritt nicht abgeschlossen werden kann, gibt die Antwort immer noch 201 mit der gültigen Analyse und einem Warnungsarray zurück, das erklärt, was übersprungen wurde. Überprüfen Sie die Warnungen, anstatt davon auszugehen, dass KI-Ergebnisse immer vorhanden sind.
  • Jeder abgeschlossene KI-Schritt fügt dem Aufruf 0,10 $ hinzu. KI-Schritte, die fehlschlagen oder abbrechen, werden nie berechnet, und /enhance wird nur für die erfolgreich abgeschlossenen KI-Schritte berechnet, ohne Grundgebühr für den Aufruf.
  • Wenn jeder von Ihnen angeforderte KI-Schritt fehlschlägt, ist der Aufruf kostenlos und die Antwort enthält nur Warnungen ohne Daten. Ihre gespeicherte Analyse bleibt in diesem Fall unverändert, sodass die Kopie, die Sie bereits haben, immer noch aktuell ist. Endpunkte zur Erstellung von Angeboten geben immer Daten zurück, da ihre Grundgebühr den Bericht selbst abdeckt.

Erforderliche Parameter

analysisIdstring

The _id of an analysis previously created with your API key

Beispiel: 000000000000000000000000

Optionale Parameter

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.

Beispiel: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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 KI-Anreicherung ist pro Anfrage über addAIComps und addAIExpenseEstimates optional und jeder KI-Schritt ist zeitlich begrenzt und scheitert offen. Eine Anfrage, die nach KI gefragt hat, gibt immer noch 201 mit einer vollständigen, vollständig neu berechneten Analyse zurück; alles, was nicht ausgeführt werden konnte, wird im Warnungsarray auf oberster Ebene gemeldet, anstatt einen Fehler auszulösen.

Timeouts und Rate-Limits

  • KI-Arbeiten haben ein Budget von 90 Sekunden, gemessen ab dem Beginn der Anfrage, nicht ab dem Beginn des KI-Schritts. Geocodierung und Analyseerstellung zählen daher mit. Wenn das Budget aufgebraucht ist, wird die Analyse ohne den unvollendeten KI-Schritt und eine Timeout-Warnung zurückgegeben.
  • 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 KI-Schritt zu wiederholen, rufen Sie POST /v1/external/analysis/enhance mit derselben analysisId auf, anstatt die Analyse erneut zu erstellen. Enhance verursacht keine Grundgebühr, daher kostet eine Wiederholung nur die KI-Schritte, die abgeschlossen werden.

Warnungen in der Antwort

Eine 201-Antwort kann immer noch ein Warnungsarray enthalten. Behandeln Sie es als Aufzeichnung dessen, was nicht ausgeführt wurde, und überprüfen Sie es, bevor Sie davon ausgehen, dass KI-Ergebnisse vorhanden sind. Jeder hier gemeldete Schritt wurde übersprungen, und übersprungene Schritte werden nie in Rechnung gestellt.

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
Geeignete Fotos von Angeboten für die Adresse waren nicht rechtzeitig fertig: keine wurden gefunden, zu wenige waren verwendbar, oder die Galerie wurde noch verarbeitet, als das Budget aufgebraucht war. Fotos werden im Hintergrund gesammelt, nachdem eine Analyse erstellt wurde. Ein erneuter Versuch mit /enhance kurz danach gelingt 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 Modell-Anbieter war nicht verfügbar. Dies ist vorübergehend, versuchen Sie es also 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 weiterer KI-Comps-Lauf arbeitet bereits an dieser Analyse. Warten Sie, bevor Sie es erneut versuchen: Der Lauf hält eine Sperre für bis zu 10 Minuten.
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 Modell-Anbieter war nicht verfügbar. Dies ist vorübergehend, versuchen Sie es also 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

Jeder erfolgreich abgeschlossene KI-Schritt fügt dem Aufruf 0,10 $ hinzu. Schritte, die abbrechen, fehlschlagen oder auf die vorhandene Prognose zurückfallen, werden nicht berechnet (aiComps.applied auf false gesetzt bedeutet, dass KI-Vergleiche nicht abgerechnet wurden), und ein /enhance-Aufruf, bei dem jeder angeforderte Schritt übersprungen wurde, wird überhaupt nicht berechnet.

Rate Limits

Limits zählen pro aufrufender IP, es sei denn, eine Zeile besagt etwas anderes. Throttled Responses tragen X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Anfrage, die ein Limit überschreitet, gibt 429 mit einem Retry-After-Header in Sekunden zurück und wird nie berechnet. Warten Sie also so lange, bevor Sie es erneut versuchen.

100 pro Sekunde
Jede /v1/external Route.
5 pro Minute
POST /v1/external/analysis/enhance und Listing Optimizer Läufe (run_listing_optimization).
10 pro Minute
Anfragen, die addAIComps oder addAIExpenseEstimates festlegen, pro API-Schlüssel, mit maximal 2 gleichzeitig.
10 bis 60 pro Minute
Live-Angebote 10; Immobiliendetails, Mietpreisschätzungen und Konto 30; Protokollierung von Materialteilnahmestunden 60.
2.000 pro Tag
Datensuche (Umsatzschätzungen, Übernachtungspreise, Vergleichsangebote, Angebote und Fotos, Live-Angebote, Immobiliendetails und Mietpreisschätzungen) pro Konto, gemeinsam genutzt von der REST-API und dem MCP-Server, und bis zu 2.500 Angebotszeilen pro Tag. Die Obergrenze wird um 00:00 UTC zurückgesetzt.

Fehlercodes

Die BNBCalc API verwendet Standard-HTTP-Statuscodes, um Erfolg oder Fehlschlag von API-Anfragen anzuzeigen. Erfolgreiche Anfragen liefern 2xx-Codes, Fehler liefern 4xx- oder 5xx-Codes mit zusätzlichen Fehlerinformationen im Antworttext. Fehlgeschlagene Anfragen (4xx oder 5xx) werden nie berechnet.

201
Erstellt: Die Analyse wurde erstellt oder verbessert und ist in der Antwort enthalten
400
Fehlerhafte Anfrage - Ungültige Parameter
401
Nicht autorisiert - Ungültiger API-Schlüssel
402
Payment Required - Das Konto des Schlüssels hat kein aktives API-Abonnement oder kein Listing-Optimizer-Guthaben mehr
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - Die angeforderte Analyse, das Inserat oder der Standort wurde nicht gefunden
409
Conflict - Ein KI- oder Listing-Optimizer-Lauf ist bereits aktiv, die Analyse wurde seit dem Lesen geändert oder der Bericht ist noch nicht fertig
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 - Ein KI-Modell oder die Inseratsquelle ist vorübergehend nicht verfügbar; versuchen Sie es später erneut
API-Status prüfen

API-Guides

API-Preise

Sehen Sie, was die BNBCalc API kostet: $0 im Monat, $0.20 pro Bericht und $0.10 pro abgeschlossenem KI-Schritt.

API-Anwendungsfälle

Sehen Sie, wie PropTech-Plattformen, Investoren, Kreditgeber, Betreiber und Analysten die API in Produktions-Workflows nutzen.

Datenabdeckung

Verstehen Sie den internationalen Immobilienbereich, vergleichsbasierte Schätzungen, Standortangaben und wo die API passt.

API-Vergleich

Sehen Sie, wie die BNBCalc API im Vergleich zur AirDNA API und anderen Airbnb Daten APIs in Bezug auf Zugriff, Preismodell und Ausgabe abschneidet.

Google Tabellen

Analysieren Sie eine Liste von Adressen in Google Tabellen mit einem kurzen Apps Script.

MCP-Server

Verbinden Sie Claude, Cursor oder VS Code mit BNBCalc und führen Sie Umsatzschätzungen und Deal-Analysen von Ihrem KI-Assistenten aus.

Anleitungen zur MCP-Einrichtung

Verbinden Sie Claude, ChatGPT, Claude Code, Cursor oder VS Code Schritt für Schritt mit dem MCP-Server.

MCP-Referenz

Wie der MCP-Server authentifiziert, jedes Werkzeug mit seinem Preis, die Genehmigung von kostenpflichtigen Werkzeugen und Grenzen.

Änderungsprotokoll

Was hat sich in der REST API und dem MCP-Server geändert, neueste zuerst.

Status

Live-Prüfungen der REST-API und des MCP-Servers.