Dokumentacja API danych Airbnb

Użyj API danych Airbnb BNBCalc, aby uzyskać przychody z nieruchomości, obłożenie, ADR, aktywne porównywalne oferty Airbnb, percentyle, metryki inwestycyjne i publiczne adresy URL raportów do aplikacji, raportów, oceny ryzyka i narzędzi zarządzania.

Specyfikacja OpenAPI
URL bazowy
https://atlas.bnbcalc.com
Nagłówek klucza API
x-bnbcalc-api-key
Serwer MCP
https://atlas.bnbcalc.com/mcp
Zaktualizowano

Pierwsze kroki

  1. 1

    Utwórz konto BNBCalc i wygeneruj klucz API w ustawieniach panelu.

  2. 2

    Przesyłaj swój klucz w nagłówku x-bnbcalc-api-key przy każdym żądaniu.

  3. 3

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

Wszystkie punkty końcowe API korzystają z HTTPS i zwracają odpowiedzi w formacie JSON. Przechowuj klucze API na swoim serwerze, nie w kodzie przeglądarki lub klienta mobilnego. Zewnętrzne trasy API są obecnie ograniczone do 100 żądań na sekundę i używają standardowych kodów odpowiedzi HTTP, aby wskazać sukces lub porażkę.

Zaimportuj opis OpenAPI 3.1 do Postman, Insomnia lub generatora klienta: https://www.bnbcalc.com/developers/openapi.json

Nie piszesz kodu? Zamiast tego użyj BNBCalc z Claude, ChatGPT lub innej aplikacji AI. Przewodnik konfiguracji MCP

Uwierzytelnianie

Wszystkie żądania API wymagają uwierzytelnienia za pomocą klucza API. Klucze API są powiązane z Twoim kontem BNBCalc, powinny być przechowywane po stronie serwera i nigdy nie powinny być ujawniane w kodzie front-end. Dodaj swój klucz API do nagłówka żądania, jak pokazano poniżej:

HTTP

x-bnbcalc-api-key: YOUR_API_KEY

Możesz wygenerować klucze API samodzielnie z sekcji ustawień konta. Do każdego żądania API dołącz nagłówek x-bnbcalc-api-key, aby się uwierzytelnić.

Twórz analizy

  • 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.
  • Gdy krok SI nie może zostać ukończony, odpowiedź nadal zwraca kod 201 z prawidłową analizą i tablicą ostrzeżeń wyjaśniających, co zostało pominięte. Sprawdź ostrzeżenia, zamiast zakładać, że wyniki SI są zawsze dostępne.
  • Każdy ukończony krok AI dodaje 0,10 $ do połączenia. Kroki AI, które zawiodą lub się zakończą, nigdy nie są naliczane, a /enhance jest rozliczane tylko za kroki AI, które zakończyły się pomyślnie, bez podstawowej opłaty za połączenie.

POST /v1/external/analysis/create/buy

Utwórz analizę zakupu

Utwórz nową analizę zakupu nieruchomości. Wymaga szczegółów dotyczących nieruchomości, informacji o lokalizacji oraz ceny zakupu.

Narzędzie MCPcreate_buy_analysis

Parametry Lokalizacji (Warunkowe)

⚠️ Podaj lat I lng, LUB podaj fullAddress. Wymagana jest co najmniej jedna metoda.

latnumber

Współrzędna szerokości geograficznej (musi być podana z lng, jeśli fullAddress nie jest używany)

Przykład: 27.7676

lngnumber

Współrzędna długości geograficznej (musi być podana z lat, jeśli fullAddress nie jest używany)

Przykład: -82.6403

fullAddressstring

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)

Przykład: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parametry Wymagane

purchasePriceUSDnumber

Cena zakupu w USD

Przykład: 350000

bedroomsnumber

Liczba sypialni

Przykład: 3

bathroomsnumber

Liczba łazienek

Przykład: 2

accomodatesnumber

Liczba gości, których nieruchomość może pomieścić

Przykład: 6

Parametry Opcjonalne

monthlyRentUSDnumber

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy

Przykład: 2500

interestRatePercentagenumber

Oprocentowanie w procentach (0-15)

Przykład: 5.1

downPaymentPercentagenumber

Procentowy wkład własny (0-40)

Przykład: 25

mortgageLengthnumber

Okres kredytowania hipotecznego w latach (0-30)

Przykład: 15

squareFeetnumber

Powierzchnia nieruchomości w stopach kwadratowych

Przykład: 1500

statestring

Nazwa stanu

Przykład: Florida

citystring

Nazwa miasta

Przykład: St. Petersburg

countystring

Nazwa hrabstwa

Przykład: Pinellas County

postalCodestring

Kod pocztowy

Przykład: 33703

countrystring

Nazwa kraju

Przykład: United States

streetstring

Nazwa ulicy

Przykład: 2nd Avenue North

streetNumberstring

Numer domu

Przykład: 4935

unitstring

Numer jednostki/mieszkania, jeżeli dotyczy

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.

Przykład: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Przykład: 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
}'

Przykładowa odpowiedź

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

Utwórz analizę arbitrażu

Utwórz nową analizę arbitrażu (arbitraż najmu) dla nieruchomości. Używa tych samych wymaganych pól co analiza zakupu.

Parametry Lokalizacji (Warunkowe)

⚠️ Podaj lat I lng, LUB podaj fullAddress. Wymagana jest co najmniej jedna metoda.

latnumber

Współrzędna szerokości geograficznej (musi być podana z lng, jeśli fullAddress nie jest używany)

Przykład: 27.7676

lngnumber

Współrzędna długości geograficznej (musi być podana z lat, jeśli fullAddress nie jest używany)

Przykład: -82.6403

fullAddressstring

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)

Przykład: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parametry Wymagane

monthlyRentUSDnumber

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy

Przykład: 2500

bedroomsnumber

Liczba sypialni

Przykład: 3

bathroomsnumber

Liczba łazienek

Przykład: 2

accomodatesnumber

Liczba gości, których nieruchomość może pomieścić

Przykład: 6

Parametry Opcjonalne

purchasePriceUSDnumber

Cena zakupu w USD

Przykład: 350000

squareFeetnumber

Powierzchnia nieruchomości w stopach kwadratowych

Przykład: 1500

statestring

Nazwa stanu

Przykład: Florida

citystring

Nazwa miasta

Przykład: St. Petersburg

countystring

Nazwa hrabstwa

Przykład: Pinellas County

postalCodestring

Kod pocztowy

Przykład: 33703

countrystring

Nazwa kraju

Przykład: United States

streetstring

Nazwa ulicy

Przykład: 2nd Avenue North

streetNumberstring

Numer domu

Przykład: 4935

unitstring

Numer jednostki/mieszkania, jeżeli dotyczy

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.

Przykład: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Przykład: 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
}'

Przykładowa odpowiedź

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

Utwórz własną analizę

Utwórz nową analizę posiadanej nieruchomości. Wykorzystuje te same wymagane pola, co analiza zakupu.

Narzędzie MCPcreate_owned_analysis

Parametry Lokalizacji (Warunkowe)

⚠️ Podaj lat I lng, LUB podaj fullAddress. Wymagana jest co najmniej jedna metoda.

latnumber

Współrzędna szerokości geograficznej (musi być podana z lng, jeśli fullAddress nie jest używany)

Przykład: 27.7676

lngnumber

Współrzędna długości geograficznej (musi być podana z lat, jeśli fullAddress nie jest używany)

Przykład: -82.6403

fullAddressstring

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)

Przykład: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parametry Wymagane

purchasePriceUSDnumber

Cena zakupu w USD

Przykład: 350000

downPaymentPercentagenumber

Procentowy wkład własny (0-40)

Przykład: 20

interestRatePercentagenumber

Oprocentowanie w procentach (0-15)

Przykład: 5.1

mortgageLengthnumber

Okres kredytowania hipotecznego w latach (0-30)

Przykład: 30

yearsRemainingOnMortgagenumber

Pozostałe lata kredytu hipotecznego (Nie mogą być wyższe niż okres kredytu hipotecznego)

bedroomsnumber

Liczba sypialni

Przykład: 3

bathroomsnumber

Liczba łazienek

Przykład: 2

accomodatesnumber

Liczba gości, których nieruchomość może pomieścić

Przykład: 6

Parametry Opcjonalne

monthlyRentUSDnumber

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy

Przykład: 2500

squareFeetnumber

Powierzchnia nieruchomości w stopach kwadratowych

Przykład: 1500

statestring

Nazwa stanu

Przykład: Florida

citystring

Nazwa miasta

Przykład: St. Petersburg

countystring

Nazwa hrabstwa

Przykład: Pinellas County

postalCodestring

Kod pocztowy

Przykład: 33703

countrystring

Nazwa kraju

Przykład: United States

streetstring

Nazwa ulicy

Przykład: 2nd Avenue North

streetNumberstring

Numer domu

Przykład: 4935

unitstring

Numer jednostki/mieszkania, jeżeli dotyczy

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.

Przykład: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Przykład: 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
}'

Przykładowa odpowiedź

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

Utwórz analizę Cohost

Utwórz historię współgospodarzy

Parametry Lokalizacji (Warunkowe)

⚠️ Podaj lat I lng, LUB podaj fullAddress. Wymagana jest co najmniej jedna metoda.

latnumber

Współrzędna szerokości geograficznej (musi być podana z lng, jeśli fullAddress nie jest używany)

Przykład: 27.7676

lngnumber

Współrzędna długości geograficznej (musi być podana z lat, jeśli fullAddress nie jest używany)

Przykład: -82.6403

fullAddressstring

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)

Przykład: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parametry Wymagane

bedroomsnumber

Liczba sypialni

Przykład: 3

bathroomsnumber

Liczba łazienek

Przykład: 2

accomodatesnumber

Liczba gości, których nieruchomość może pomieścić

Przykład: 6

Parametry Opcjonalne

cohostCommissionPercentagenumber

Procent prowizji współgospodarza

Przykład: 10

squareFeetnumber

Powierzchnia nieruchomości w stopach kwadratowych

Przykład: 1500

statestring

Nazwa stanu

Przykład: Florida

citystring

Nazwa miasta

Przykład: St. Petersburg

countystring

Nazwa hrabstwa

Przykład: Pinellas County

postalCodestring

Kod pocztowy

Przykład: 33703

countrystring

Nazwa kraju

Przykład: United States

streetstring

Nazwa ulicy

Przykład: 2nd Avenue North

streetNumberstring

Numer domu

Przykład: 4935

unitstring

Numer jednostki/mieszkania, jeżeli dotyczy

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.

Przykład: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Przykład: 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
}'

Przykładowa odpowiedź

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

Wzbogacanie AI

POST /v1/external/analysis/enhance

Ulepsz analizę za pomocą AI

Uruchamia wzbogacanie przez AI na podstawie już utworzonej analizy i zwraca przeliczoną analizę. Użyj tego, gdy chcesz zastosować wybrane przez AI porównywalne obiekty lub szacunki kosztów przez AI po fakcie, lub gdy wolisz, aby pierwotne wywołanie tworzenia było szybkie.

Narzędzie MCPenhance_analysis
  • AI requests are slower than standard calls. Allow up to 90 seconds and set your client timeout to at least 300 seconds. AI work is time-bounded, so a request always returns a usable analysis rather than hanging.
  • AI-selected comparables are available for United States properties and require at least 8 usable listing photos for the address. Listing photos are gathered in the background when an analysis is created, so calling enhance shortly afterwards is faster than requesting comparables during creation.
  • Gdy krok SI nie może zostać ukończony, odpowiedź nadal zwraca kod 201 z prawidłową analizą i tablicą ostrzeżeń wyjaśniających, co zostało pominięte. Sprawdź ostrzeżenia, zamiast zakładać, że wyniki SI są zawsze dostępne.
  • Każdy ukończony krok AI dodaje 0,10 $ do połączenia. Kroki AI, które zawiodą lub się zakończą, nigdy nie są naliczane, a /enhance jest rozliczane tylko za kroki AI, które zakończyły się pomyślnie, bez podstawowej opłaty za połączenie.
  • Jeśli każdy żądany przez Ciebie krok AI zawiedzie, połączenie będzie bezpłatne, a odpowiedź będzie zawierać tylko ostrzeżenia, bez danych. Twoja zapisana analiza pozostaje niezmieniona w takim przypadku, więc kopia, którą już masz, jest nadal aktualna. Punkty końcowe tworzenia zawsze zwracają dane, ponieważ ich opłata bazowa obejmuje sam raport.

Parametry Wymagane

analysisIdstring

The _id of an analysis previously created with your API key

Przykład: 000000000000000000000000

Parametry Opcjonalne

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.

Przykład: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Przykład: 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
}'

Przykładowa odpowiedź

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

Zachowanie wzbogacania AI

Wzbogacanie SI jest opcjonalne na żądanie za pośrednictwem addAIComps i addAIExpenseEstimates, a każdy krok SI ma ograniczony czas i otwarcie kończy się niepowodzeniem. Żądanie, które prosiło o SI, nadal zwraca 201 z kompletną, w pełni przeliczoną analizą; wszystko, czego nie udało się uruchomić, jest zgłaszane w tablicy ostrzeżeń najwyższego poziomu zamiast generowania błędu.

Limity czasu i ograniczenia liczby żądań

  • Praca AI ma budżet 90 sekund liczony od rozpoczęcia żądania, a nie od momentu rozpoczęcia kroku AI, więc geokodowanie i tworzenie analizy są wliczane do tego czasu. Po wyczerpaniu budżetu analiza jest zwracana bez niedokończonego kroku AI i z ostrzeżeniem o przekroczeniu czasu.
  • Ustaw timeout klienta na co najmniej 300 sekund. Większość wywołań AI zwraca odpowiedź znacznie szybciej, ale klient, który przerywa wcześniej niż termin serwera, powoduje, że rozliczalna, ukończona analiza staje się utraconą odpowiedzią.
  • Wywołanie modelu wymaga co najmniej 45 sekund pozostałego budżetu, aby się rozpocząć. Żądanie, które zużyło większość budżetu czekając na zdjęcia oferty, zwraca ai_comps_timed_out bez wywoływania modelu, zamiast rozpoczynać uruchomienie, którego nie dałoby się dokończyć.
  • Żądania z włączoną flagą AI są ograniczone per klucz API: 10 na minutę, maksymalnie 2 równocześnie. Przekroczenie któregokolwiek z limitów powoduje zwrot 429 z nagłówkiem Retry-After, a nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset są ustawiane dla każdego żądania AI. Wywołania bez flagi AI nie podlegają temu limitowi.
  • Aby ponowić pominięty krok AI, wywołaj POST /v1/external/analysis/enhance z tym samym analysisId zamiast tworzyć analizę od nowa. Enhance nie ponosi podstawowej opłaty za połączenie, więc ponowne próby kosztują tylko ukończone kroki AI.

Ostrzeżenia w odpowiedzi

Odpowiedź 201 nadal może zawierać tablicę ostrzeżeń. Traktuj ją jako zapis tego, co nie zostało wykonane, i sprawdź ją, zanim założysz, że wyniki SI są obecne. Każdy zgłoszony tutaj krok został pominięty, a pominięte kroki nigdy nie są fakturowane.

ai_comps_requires_user_scoped_api_key
AI comps wymagają klucza API powiązanego z kontem użytkownika. Nie udało się przypisać klucza do właściciela, więc comp selector nigdy się nie uruchomił.
ai_comps_unavailable_for_property
AI comps są dostępne tylko dla nieruchomości w Stanach Zjednoczonych, a przechowywana analiza znajduje się poza tym zakresem.
ai_comps_photos_not_ready
Odpowiednie zdjęcia ofert pod wskazany adres nie były gotowe na czas: nie znaleziono żadnych, zbyt mało było użytecznych lub galeria nadal się przetwarzała, gdy wyczerpał się budżet. Zdjęcia są zbierane w tle po utworzeniu analizy, więc ponowne próby z /enhance wkrótce potem zazwyczaj kończą się powodzeniem.
ai_comps_timed_out
Budżet AI wyczerpał się zanim model odpowiedział, więc zachowano deterministyczne porównania i prognozę przychodów.
ai_comps_benchmark_fallback
Model się uruchomił, ale wybrał zbyt mało porównywalnych ofert, by utworzyć benchmark, więc zachowano istniejącą prognozę przychodów. Nic nie zostało zapisane w analizie i krok nie został obciążony.
ai_comps_model_unavailable
Dostawca modelu był niedostępny. Jest to tymczasowe, więc spróbuj ponownie z /enhance.
ai_comps_already_applied
Ta analiza ma już prawidłowy benchmark AI, więc nic nie zostało uruchomione ponownie ani naliczone. Edycja nieruchomości unieważnia go, a kolejne wywołanie wykona się naprawdę.
ai_comps_run_in_progress
Inny przebieg AI porównawczy już pracuje nad tą analizą. Poczekaj przed ponowną próbą: przebieg blokuje dostęp przez maksymalnie 10 minut.
ai_comps_analysis_changed
Analiza została zmieniona w trakcie działania modelu, więc benchmark nie został zapisany zamiast nadpisać nowsze wartości. Spróbuj ponownie z /enhance.
ai_comps_forbidden
Analiza nie została utworzona tym kluczem API, więc AI comps nie mogły zostać na niej uruchomione.
ai_comps_failed
AI comps nie mogły zostać ukończone z innego powodu. Sama analiza jest ważna i niezmieniona.
ai_expense_estimates_timed_out
Budżet AI wyczerpał się zanim estimator kosztów zwrócił wynik, więc zachowano domyślne koszty operacyjne.
ai_expense_estimates_no_proposals
Estimator nie wygenerował propozycji kosztów dla tej nieruchomości, więc żaden koszt operacyjny nie został zmieniony.
ai_expense_estimates_stale_preview
Analiza zmieniła się w trakcie przygotowywania estymatu, więc estymat został odrzucony zamiast zostać zastosowany do nieaktualnych danych. Spróbuj ponownie z /enhance.
ai_expense_estimates_model_unavailable
Dostawca modelu był niedostępny. Jest to tymczasowe, więc spróbuj ponownie z /enhance.
ai_expense_estimates_already_applied
Ta analiza ma już koszty oszacowane przez AI, więc nic nie zostało uruchomione ponownie ani naliczone.
ai_expense_estimates_unavailable_for_property
Żadne pole kosztów operacyjnych w tej analizie nie kwalifikowało się do szacowania przez AI, więc zachowano jej domyślne koszty.
ai_expense_estimates_forbidden
Analiza nie została utworzona tym kluczem API, więc szacunki kosztów AI nie mogły zostać na niej uruchomione.
ai_expense_estimates_failed
Szacunki kosztów AI nie mogły zostać zastosowane. Analiza zachowuje swoje domyślne koszty operacyjne.

Dopasowuj na podstawie prefiksów ai_comps_ i ai_expense_estimates_, a nie dokładnego ciągu znaków: każdy inny kod z tymi prefiksami oznacza, że dany krok nie powiódł się, nie został zastosowany i nie został obciążony.

Przykładowa odpowiedź

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

aiComps.warnings

Zagnieżdżona tablica aiComps.warnings to inny sygnał niż tablica na najwyższym poziomie: opisuje jakość puli porównywalnych ofert, na której pracował model, a nie krok, który się nie powiódł. Sprawdź aiComps.applied, aby dowiedzieć się, czy benchmark AI został faktycznie zapisany w analizie.

thin_benchmark_pool
Benchmark opierał się na mniej niż czterech porównaniach, więc bazuje na małej próbie.
no_benchmark_comps
Żadne porównanie nie przeszło selekcji. Benchmark jest pusty, a prognoza przychodów pozostała niezmieniona.
ai_benchmark_fallback_to_projected_revenue
Wybrano mniej niż trzy porównania, więc zamiast benchmarku AI zachowano istniejącą prognozę przychodów. Jest to ten sam wynik zgłaszany na najwyższym poziomie jako ai_comps_benchmark_fallback.
minimum_benchmark_pool_backfill
Pula benchmarkowa została uzupełniona porównaniami, których model nie wybrał, aby osiągnąć minimalną liczbę.

Rozliczanie przy częściowych operacjach AI

Każdy ukończony krok AI dodaje 0,10 $ do połączenia. Kroki, które wygasają, zawiodą lub wrócą do istniejącej projekcji, nie są naliczane (aiComps.applied ustawione na fałsz oznacza, że porównania AI nie były naliczane), a wywołanie /enhance, w którym pominięto każdy żądany krok, nie jest w ogóle naliczane.

Limity szybkości

Limity są naliczane na adres IP wywołującego, chyba że w wierszu podano inaczej. Ograniczone odpowiedzi zawierają nagłówki X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Żądanie przekraczające limit zwraca kod 429 z nagłówkiem Retry-After w sekundach i nigdy nie jest rozliczane, więc poczekaj ten czas przed ponowieniem próby.

100 na sekundę
Każda trasa /v1/external.
5 na minutę
POST /v1/external/analysis/enhance i uruchomienia Listing Optimizer (run_listing_optimization).
10 na minutę
Żądania ustawiające addAIComps lub addAIExpenseEstimates, na klucz API, z maksymalnie 2 aktywnymi.
10 do 60 na minutę
Listy na żywo 10; szczegóły nieruchomości, szacunki czynszu i konto 30; godziny udziału w materiałach ewidencyjnych 60.
2000 na dzień
Wyszukiwania danych (szacunki przychodów, stawki za noc, porównania, oferty i zdjęcia, oferty na żywo, szczegóły nieruchomości i szacunki czynszu) na konto, współdzielone przez API REST i serwer MCP, oraz do 2500 wierszy ofert dziennie. Limit resetuje się o 00:00 UTC.

Kody błędów

API BNBCalc używa standardowych kodów stanu HTTP, aby wskazać powodzenie lub niepowodzenie zapytań. Udane zapytania zwracają kody 2xx, a błędy kody 4xx lub 5xx z dodatkowymi informacjami w treści odpowiedzi. Nieudane zapytania (4xx lub 5xx) nigdy nie są rozliczane.

201
Utworzono: analiza została utworzona lub ulepszona i znajduje się w odpowiedzi
400
Błędne żądanie - Nieprawidłowe parametry
401
Nieautoryzowany - Nieprawidłowy klucz API
402
Payment Required - Konto klucza nie ma aktywnej subskrypcji API lub nie ma już kredytów Listing Optimizer
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - Nie znaleziono żądanej analizy, ogłoszenia ani lokalizacji
409
Conflict - Uruchomienie AI lub Listing Optimizer już trwa, analiza zmieniła się od odczytu albo raport nie jest jeszcze gotowy
429
Zbyt wiele żądań - Przekroczono limit trasy API zewnętrznego
500
Wewnętrzny błąd serwera
502
Bad Gateway - The AI model returned an unusable response
503
Service Unavailable - Model AI lub źródło ogłoszeń jest chwilowo niedostępne; spróbuj później
Sprawdź stan API

Poradniki API

Cennik API

Zobacz, ile kosztuje API BNBCalc: $0 miesięcznie, $0.20 za raport i $0.10 za każdy ukończony krok AI.

Przykłady użycia API

Zobacz, jak platformy PropTech, inwestorzy, pożyczkodawcy, operatorzy i analitycy używają API w produkcyjnych przepływach pracy.

Pokrycie danych

Zrozum międzynarodowe pokrycie nieruchomości, oszacowania oparte na porównaniach, dane lokalizacyjne i to, gdzie API pasuje.

Porównanie API

Zobacz, jak API BNBCalc wypada w porównaniu z API AirDNA i innymi API danych Airbnb pod względem dostępu, modelu cenowego i wyników.

Arkusze Google

Przeanalizuj listę adresów w Arkuszach Google za pomocą krótkiego skryptu Apps Script.

Serwer MCP

Połącz Claude, Cursor lub VS Code z BNBCalc i przeprowadzaj szacunki przychodów oraz analizy transakcji ze swojego asystenta AI.

Przewodnik konfiguracji MCP

Połącz Claude, ChatGPT, Claude Code, Cursor lub VS Code z serwerem MCP, krok po kroku.

Referencja MCP

Jak serwer MCP uwierzytelnia, każde narzędzie z ceną, zatwierdzanie płatnych narzędzi i limity.

Dziennik zmian

Co się zmieniło w API REST i serwerze MCP, od najnowszych.

Status

Sprawdzenia na żywo interfejsu API REST i serwera MCP.