Riferimento API

punti finali

POSTCrea analisi di acquisto POSTCrea analisi di arbitraggio POSTCrea un'analisi personale POSTCrea analisi Cohost

RISORSE

Primi passi Autenticazione Codici di errore

Documentazione API

Benvenuti all'API BNBCalc. Questa documentazione vi aiuterà a integrare i nostri strumenti di analisi immobiliare nella vostra applicazione.

La nostra API RESTful offre accesso programmato ai dati completi sui noleggi a breve termine di BNBCalc, alle stime dei ricavi degli immobili, all'analisi del mercato e alle proiezioni di investimento. Che tu stia sviluppando software per la gestione delle proprietà, piattaforme immobiliari o strumenti di analisi degli investimenti, la nostra API fornisce i dati di cui hai bisogno.

Primi passi

Per iniziare a utilizzare l'API BNBCalc, dovrai:

1. Crea un account BNBCalc oppure accedi al tuo account esistente

2. Vai alle impostazioni del tuo account per generare una chiave API

3. Includi la tua chiave API in tutte le richieste API utilizzando l'intestazione x-bnbcalc-api-key.

4. Inizia a fare richieste per accedere ai dati e alle analisi degli immobili.

Tutti gli endpoint API utilizzano HTTPS e restituiscono risposte in formato JSON. La nostra API segue i principi RESTful e utilizza i codici di risposta HTTP standard per indicare il successo o il fallimento.

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite una chiave API. Le chiavi API sono associate al tuo account BNBCalc e devono essere mantenute sicure. Includi la tua chiave API nell'intestazione della richiesta come mostrato di seguito:

x-bnbcalc-api-key: YOUR_API_KEY

Puoi generare chiavi API dalla pagina delle impostazioni del tuo account. Includi l'header x-bnbcalc-api-key in ogni richiesta API per autenticarti.

POST/v1/external/analysis/create/buy

Crea analisi di acquisto

Creare una nuova analisi d'acquisto per una proprietà. Richiede dettagli della proprietà, informazioni sulla posizione e prezzo d'acquisto.

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

purchasePriceUSDnumberrichiesto

Prezzo di acquisto in USD(e.g., 350000)

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

monthlyRentUSDnumberopzionale

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

interestRatePercentagenumberopzionale

Percentuale del tasso d'interesse (0-15)(e.g., 5.1)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

Numero dell'unità o dell'appartamento, se applicabile

Richiesta di esempio

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

Risposta di esempio

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

Crea analisi di arbitraggio

Crea una nuova analisi di arbitraggio (arbitraggio da affitto) per una proprietà. Utilizza gli stessi campi obbligatori dell'analisi d'acquisto.

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

monthlyRentUSDnumberrichiesto

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

purchasePriceUSDnumberopzionale

Prezzo di acquisto in USD(e.g., 350000)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

Numero dell'unità o dell'appartamento, se applicabile

Richiesta di esempio

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

Risposta di esempio

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

Crea un'analisi personale

Crea una nuova analisi della proprietà posseduta. Utilizza gli stessi campi obbligatori dell'analisi di acquisto.

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

purchasePriceUSDnumberrichiesto

Prezzo di acquisto in USD(e.g., 350000)

downPaymentPercentagenumberrichiesto

Percentuale di acconto (0-40)(e.g., 20)

interestRatePercentagenumberrichiesto

Percentuale del tasso d'interesse (0-15)(e.g., 5.1)

mortgageLengthnumberrichiesto

Durata del mutuo in anni (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberrichiesto

Anni rimanenti sul mutuo (Non può essere superiore alla durata del mutuo)

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

monthlyRentUSDnumberopzionale

Affitto mensile previsto in USD per un affitto a lungo termine(e.g., 2500)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

Numero dell'unità o dell'appartamento, se applicabile

Richiesta di esempio

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

Risposta di esempio

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

Crea analisi Cohost

Crea la cronologia dei cohost

Parametri di Posizione (Condizionali)

⚠️ Fornire lat E lng, OPPURE fornire fullAddress. È richiesto almeno un metodo.

latnumbercondizionale

Coordinata di latitudine (deve essere fornita con lng se fullAddress non è utilizzato)(e.g., 27.7676)

lngnumbercondizionale

Coordinata di longitudine (deve essere fornita con lat se fullAddress non è utilizzato)(e.g., -82.6403)

fullAddressstringcondizionale

Indirizzo completo della proprietà (può essere utilizzato al posto delle coordinate lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parametri Obbligatori

bedroomsnumberrichiesto

Numero di camere da letto(e.g., 3)

bathroomsnumberrichiesto

Numero di bagni(e.g., 2)

accomodatesnumberrichiesto

Numero di ospiti che la proprietà può accogliere(e.g., 6)

Parametri Opzionali

cohostCommissionPercentagenumberopzionale

Percentuale della commissione del co-host(e.g., 10)

squareFeetnumberopzionale

Superficie in piedi quadrati della proprietà(e.g., 1500)

statestringopzionale

Nome dello stato(e.g., Florida)

citystringopzionale

Nome della città(e.g., St. Petersburg)

countystringopzionale

Nome della contea(e.g., Pinellas County)

postalCodestringopzionale

Codice postale(e.g., 33703)

countrystringopzionale

Nome del paese(e.g., United States)

streetstringopzionale

Nome della strada(e.g., 2nd Avenue North)

streetNumberstringopzionale

Numero civico(e.g., 4935)

unitstringopzionale

Numero dell'unità o dell'appartamento, se applicabile

Richiesta di esempio

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

Risposta di esempio

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

Codici di errore

L'API BNBCalc utilizza i codici di stato HTTP standard per indicare il successo o il fallimento delle richieste API. Le richieste riuscite restituiscono codici 2xx, mentre gli errori restituiscono codici 4xx o 5xx con informazioni aggiuntive sugli errori nel corpo della risposta.

200

Successo

400

Richiesta errata - Parametri non validi

401

Non autorizzato - Chiave API non valida

429

Troppe richieste - Limite di richieste superato

500

Errore interno del server