Referencja API

punkty końcowe

POSTUtwórz analizę zakupu POSTUtwórz analizę arbitrażu POSTUtwórz własną analizę POSTUtwórz analizę Cohost

ZASOBY

Pierwsze kroki Uwierzytelnianie Kody błędów

Dokumentacja API

Witamy w interfejsie API BNBCalc. Ta dokumentacja pomoże Ci zintegrować nasze narzędzia do analizy nieruchomości z Twoją aplikacją.

Nasz interfejs RESTful API zapewnia programowy dostęp do kompleksowych danych BNBCalc dotyczących wynajmu krótkoterminowego, szacunków przychodów z nieruchomości, analiz rynku oraz prognoz inwestycyjnych. Niezależnie od tego, czy tworzysz oprogramowanie do zarządzania nieruchomościami, platformy nieruchomościowe czy narzędzia do analizy inwestycji, nasz interfejs API dostarcza niezbędne dane.

Pierwsze kroki

Aby rozpocząć korzystanie z API BNBCalc, będziesz musiał:

1. Utwórz konto BNBCalc lub zaloguj się do istniejącego konta

2. Przejdź do ustawień konta, aby wygenerować klucz API

3. Dołącz swój klucz API do wszystkich żądań API, używając nagłówka x-bnbcalc-api-key.

4. Zacznij wysyłać zapytania, aby uzyskać dostęp do danych i analiz nieruchomości.

Wszystkie punkty końcowe API korzystają z HTTPS i zwracają odpowiedzi w formacie JSON. Nasze API przestrzega zasad REST i używa standardowych kodów odpowiedzi HTTP, aby wskazać sukces lub porażkę.

Uwierzytelnianie

Wszystkie żądania API wymagają uwierzytelnienia za pomocą klucza API. Klucze API są powiązane z Twoim kontem BNBCalc i powinny być przechowywane w bezpieczny sposób. Dołącz swój klucz API w nagłówku żądania, jak pokazano poniżej:

x-bnbcalc-api-key: YOUR_API_KEY

Możesz wygenerować klucze API na stronie ustawień konta. Do każdej prośby API dodaj nagłówek x-bnbcalc-api-key, aby się uwierzytelnić.

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.

Parametry Lokalizacji (Warunkowe)

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

latnumberwarunkowe

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

lngnumberwarunkowe

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

fullAddressstringwarunkowe

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametry Wymagane

purchasePriceUSDnumberwymagane

Cena zakupu w USD(e.g., 350000)

bedroomsnumberwymagane

Liczba sypialni(e.g., 3)

bathroomsnumberwymagane

Liczba łazienek(e.g., 2)

accomodatesnumberwymagane

Liczba gości, których nieruchomość może pomieścić(e.g., 6)

Parametry Opcjonalne

monthlyRentUSDnumberopcjonalne

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy(e.g., 2500)

interestRatePercentagenumberopcjonalne

Oprocentowanie w procentach (0-15)(e.g., 5.1)

squareFeetnumberopcjonalne

Powierzchnia nieruchomości w stopach kwadratowych(e.g., 1500)

statestringopcjonalne

Nazwa stanu(e.g., Florida)

citystringopcjonalne

Nazwa miasta(e.g., St. Petersburg)

countystringopcjonalne

Nazwa hrabstwa(e.g., Pinellas County)

postalCodestringopcjonalne

Kod pocztowy(e.g., 33703)

countrystringopcjonalne

Nazwa kraju(e.g., United States)

streetstringopcjonalne

Nazwa ulicy(e.g., 2nd Avenue North)

streetNumberstringopcjonalne

Numer domu(e.g., 4935)

unitstringopcjonalne

Numer jednostki/mieszkania, jeżeli dotyczy

Przykładowe zapytanie

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 requests

data = {
  "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()

Przykładowa odpowiedź

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    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],
    "comparables": ["..."],
    "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/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.

latnumberwarunkowe

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

lngnumberwarunkowe

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

fullAddressstringwarunkowe

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametry Wymagane

monthlyRentUSDnumberwymagane

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy(e.g., 2500)

bedroomsnumberwymagane

Liczba sypialni(e.g., 3)

bathroomsnumberwymagane

Liczba łazienek(e.g., 2)

accomodatesnumberwymagane

Liczba gości, których nieruchomość może pomieścić(e.g., 6)

Parametry Opcjonalne

purchasePriceUSDnumberopcjonalne

Cena zakupu w USD(e.g., 350000)

squareFeetnumberopcjonalne

Powierzchnia nieruchomości w stopach kwadratowych(e.g., 1500)

statestringopcjonalne

Nazwa stanu(e.g., Florida)

citystringopcjonalne

Nazwa miasta(e.g., St. Petersburg)

countystringopcjonalne

Nazwa hrabstwa(e.g., Pinellas County)

postalCodestringopcjonalne

Kod pocztowy(e.g., 33703)

countrystringopcjonalne

Nazwa kraju(e.g., United States)

streetstringopcjonalne

Nazwa ulicy(e.g., 2nd Avenue North)

streetNumberstringopcjonalne

Numer domu(e.g., 4935)

unitstringopcjonalne

Numer jednostki/mieszkania, jeżeli dotyczy

Przykładowe zapytanie

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/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/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 requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/create/arb',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

Przykładowa odpowiedź

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    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],
    "comparables": ["..."],,
    "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.

Parametry Lokalizacji (Warunkowe)

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

latnumberwarunkowe

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

lngnumberwarunkowe

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

fullAddressstringwarunkowe

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametry Wymagane

purchasePriceUSDnumberwymagane

Cena zakupu w USD(e.g., 350000)

downPaymentPercentagenumberwymagane

Procentowy wkład własny (0-40)(e.g., 20)

interestRatePercentagenumberwymagane

Oprocentowanie w procentach (0-15)(e.g., 5.1)

mortgageLengthnumberwymagane

Okres kredytowania hipotecznego w latach (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberwymagane

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

bedroomsnumberwymagane

Liczba sypialni(e.g., 3)

bathroomsnumberwymagane

Liczba łazienek(e.g., 2)

accomodatesnumberwymagane

Liczba gości, których nieruchomość może pomieścić(e.g., 6)

Parametry Opcjonalne

monthlyRentUSDnumberopcjonalne

Oczekiwany miesięczny czynsz w USD za wynajem długoterminowy(e.g., 2500)

squareFeetnumberopcjonalne

Powierzchnia nieruchomości w stopach kwadratowych(e.g., 1500)

statestringopcjonalne

Nazwa stanu(e.g., Florida)

citystringopcjonalne

Nazwa miasta(e.g., St. Petersburg)

countystringopcjonalne

Nazwa hrabstwa(e.g., Pinellas County)

postalCodestringopcjonalne

Kod pocztowy(e.g., 33703)

countrystringopcjonalne

Nazwa kraju(e.g., United States)

streetstringopcjonalne

Nazwa ulicy(e.g., 2nd Avenue North)

streetNumberstringopcjonalne

Numer domu(e.g., 4935)

unitstringopcjonalne

Numer jednostki/mieszkania, jeżeli dotyczy

Przykładowe zapytanie

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 requests

data = {
  "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()

Przykładowa odpowiedź

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    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],
    "comparables": ["..."],
    "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

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.

latnumberwarunkowe

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

lngnumberwarunkowe

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

fullAddressstringwarunkowe

Pełny adres nieruchomości (może być używany zamiast współrzędnych lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametry Wymagane

bedroomsnumberwymagane

Liczba sypialni(e.g., 3)

bathroomsnumberwymagane

Liczba łazienek(e.g., 2)

accomodatesnumberwymagane

Liczba gości, których nieruchomość może pomieścić(e.g., 6)

Parametry Opcjonalne

cohostCommissionPercentagenumberopcjonalne

Procent prowizji współgospodarza(e.g., 10)

squareFeetnumberopcjonalne

Powierzchnia nieruchomości w stopach kwadratowych(e.g., 1500)

statestringopcjonalne

Nazwa stanu(e.g., Florida)

citystringopcjonalne

Nazwa miasta(e.g., St. Petersburg)

countystringopcjonalne

Nazwa hrabstwa(e.g., Pinellas County)

postalCodestringopcjonalne

Kod pocztowy(e.g., 33703)

countrystringopcjonalne

Nazwa kraju(e.g., United States)

streetstringopcjonalne

Nazwa ulicy(e.g., 2nd Avenue North)

streetNumberstringopcjonalne

Numer domu(e.g., 4935)

unitstringopcjonalne

Numer jednostki/mieszkania, jeżeli dotyczy

Przykładowe zapytanie

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 requests

data = {
  "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()

Przykładowa odpowiedź

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    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],
    "comparables": ["..."],,
    "yearOneRevenueUSD": 161193.91172942825,
    "yearOneCohostReturnUSD": 116059.61644518835,
    "yearOneCohostCommissionUSD": 32238.78234588565,
  }
}

Kody błędów

Interfejs API BNBCalc używa standardowych kodów statusu HTTP do wskazania powodzenia lub niepowodzenia zapytań API. Udane zapytania zwracają kody 2xx, natomiast błędy zwracają kody 4xx lub 5xx wraz z dodatkowymi informacjami o błędach w treści odpowiedzi.

200

Sukces

400

Błędne żądanie - Nieprawidłowe parametry

401

Nieautoryzowany - Nieprawidłowy klucz API

429

Zbyt wiele żądań - Limit żądań przekroczony

500

Wewnętrzny błąd serwera