API-Referenz

Endpunkte

POSTKaufanalyse erstellen POSTArbitrage-Analyse erstellen POSTEigene Analyse erstellen POSTCohost-Analyse erstellen

RESSOURCEN

Erste Schritte Authentifizierung Fehlercodes

API-Dokumentation

Willkommen zur BNBCalc-API. Diese Dokumentation hilft Ihnen dabei, unsere Werkzeuge zur Immobilienanalyse in Ihre Anwendung zu integrieren.

Unsere RESTful API ermöglicht den programmgesteuerten Zugriff auf BNBCalc's umfassende Daten zu Kurzzeitvermietungen, Schätzungen der Objekterlöse, Marktanalysen und Investitionsprognosen. Egal, ob Sie eine Software für Immobilienverwaltung, Immobilienportale oder Werkzeuge zur Investitionsanalyse entwickeln, unsere API liefert die benötigten Daten.

Erste Schritte

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

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

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

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

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

Alle API-Endpunkte nutzen HTTPS und liefern JSON-Antworten zurück. Unsere API folgt RESTful-Prinzipien und verwendet standardmäßige HTTP-Antwortcodes, um Erfolg oder Misserfolg anzuzeigen.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel. API-Schlüssel sind mit Ihrem BNBCalc-Konto verknüpft und sollten sicher aufbewahrt werden. Fügen Sie Ihren API-Schlüssel dem Anfrage-Header wie unten gezeigt hinzu:

x-bnbcalc-api-key: YOUR_API_KEY

Sie können API-Schlüssel über Ihre Kontoeinstellungsseite generieren. Fügen Sie bei jeder API-Anfrage den Header x-bnbcalc-api-key zur Authentifizierung hinzu.

POST/v1/external/analysis/create/buy

Kaufanalyse erstellen

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

Standortparameter (Bedingt)

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

latnumberbedingt

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

lngnumberbedingt

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

fullAddressstringbedingt

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

Erforderliche Parameter

purchasePriceUSDnumbererforderlich

Kaufpreis in USD(e.g., 350000)

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

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

Optionale Parameter

monthlyRentUSDnumberoptional

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

interestRatePercentagenumberoptional

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

squareFeetnumberoptional

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

statestringoptional

Name des Staates(e.g., Florida)

citystringoptional

Stadtname(e.g., St. Petersburg)

countystringoptional

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

postalCodestringoptional

Postleitzahl(e.g., 33703)

countrystringoptional

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

streetstringoptional

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

streetNumberstringoptional

Hausnummer(e.g., 4935)

unitstringoptional

Wohnungs-/Einheitsnummer, falls zutreffend

Beispielanfrage

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/buy \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/buy',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
})
  }
);
const data = await response.json();

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

Beispielantwort

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

Arbitrage-Analyse erstellen

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

Standortparameter (Bedingt)

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

latnumberbedingt

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

lngnumberbedingt

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

fullAddressstringbedingt

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

Erforderliche Parameter

monthlyRentUSDnumbererforderlich

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

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

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

Optionale Parameter

purchasePriceUSDnumberoptional

Kaufpreis in USD(e.g., 350000)

squareFeetnumberoptional

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

statestringoptional

Name des Staates(e.g., Florida)

citystringoptional

Stadtname(e.g., St. Petersburg)

countystringoptional

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

postalCodestringoptional

Postleitzahl(e.g., 33703)

countrystringoptional

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

streetstringoptional

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

streetNumberstringoptional

Hausnummer(e.g., 4935)

unitstringoptional

Wohnungs-/Einheitsnummer, falls zutreffend

Beispielanfrage

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

Beispielantwort

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

Eigene Analyse erstellen

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

Standortparameter (Bedingt)

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

latnumberbedingt

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

lngnumberbedingt

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

fullAddressstringbedingt

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

Erforderliche Parameter

purchasePriceUSDnumbererforderlich

Kaufpreis in USD(e.g., 350000)

downPaymentPercentagenumbererforderlich

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

interestRatePercentagenumbererforderlich

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

mortgageLengthnumbererforderlich

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

yearsRemainingOnMortgagenumbererforderlich

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

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

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

Optionale Parameter

monthlyRentUSDnumberoptional

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

squareFeetnumberoptional

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

statestringoptional

Name des Staates(e.g., Florida)

citystringoptional

Stadtname(e.g., St. Petersburg)

countystringoptional

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

postalCodestringoptional

Postleitzahl(e.g., 33703)

countrystringoptional

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

streetstringoptional

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

streetNumberstringoptional

Hausnummer(e.g., 4935)

unitstringoptional

Wohnungs-/Einheitsnummer, falls zutreffend

Beispielanfrage

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/owned \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/owned',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
})
  }
);
const data = await response.json();

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

Beispielantwort

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

Cohost-Analyse erstellen

Co-Host-Historie erstellen

Standortparameter (Bedingt)

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

latnumberbedingt

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

lngnumberbedingt

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

fullAddressstringbedingt

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

Erforderliche Parameter

bedroomsnumbererforderlich

Anzahl der Schlafzimmer(e.g., 3)

bathroomsnumbererforderlich

Anzahl der Badezimmer(e.g., 2)

accomodatesnumbererforderlich

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

Optionale Parameter

cohostCommissionPercentagenumberoptional

Cohost-Provisionsprozentsatz(e.g., 10)

squareFeetnumberoptional

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

statestringoptional

Name des Staates(e.g., Florida)

citystringoptional

Stadtname(e.g., St. Petersburg)

countystringoptional

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

postalCodestringoptional

Postleitzahl(e.g., 33703)

countrystringoptional

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

streetstringoptional

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

streetNumberstringoptional

Hausnummer(e.g., 4935)

unitstringoptional

Wohnungs-/Einheitsnummer, falls zutreffend

Beispielanfrage

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/cohost \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
})
  }
);
const data = await response.json();

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

Beispielantwort

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

Fehlercodes

Die BNBCalc API verwendet standardmäßige HTTP-Antwort-Statuscodes, um den Erfolg oder Misserfolg von API-Anfragen anzuzeigen. Erfolgreiche Anfragen liefern 2xx Codes, während Fehler 4xx oder 5xx Codes mit zusätzlichen Fehlerinformationen im Antwortkörper zurückgeben.

200

Erfolg

400

Fehlerhafte Anfrage - Ungültige Parameter

401

Nicht autorisiert - Ungültiger API-Schlüssel

429

Zu viele Anfragen - Ratenlimit überschritten

500

Interner Serverfehler