Referencia de la API

puntos finales

POSTCrear análisis de compra POSTCrear análisis de arbitraje POSTCrear análisis propio POSTCrear análisis de Cohost

RECURSOS

Primeros pasos Autenticación Códigos de error

Documentación de la API

Bienvenido a la API de BNBCalc. Esta documentación le ayudará a integrar nuestras herramientas de análisis de propiedades en su aplicación.

Nuestra API RESTful ofrece acceso programático a los completos datos de alquiler a corto plazo de BNBCalc, estimaciones de ingresos de propiedades, análisis de mercado y proyecciones de inversión. Ya sea que estés desarrollando software de gestión inmobiliaria, plataformas inmobiliarias o herramientas de análisis de inversión, nuestra API te proporciona los datos que necesitas.

Primeros pasos

Para empezar a usar la API BNBCalc, necesitarás:

1. Crea una cuenta en BNBCalc o inicia sesión en tu cuenta existente

2. Dirígete a la configuración de tu cuenta para generar una clave API

3. Incluye tu clave de API en todas las solicitudes de la API utilizando el encabezado x-bnbcalc-api-key.

4. Empieza a hacer solicitudes para acceder a los datos y análisis de propiedades.

Todos los endpoints de la API utilizan HTTPS y devuelven respuestas en formato JSON. Nuestra API sigue los principios RESTful y utiliza códigos de respuesta HTTP estándar para indicar el éxito o el fracaso.

Autenticación

Todas las solicitudes de API requieren autenticación mediante una clave de API. Las claves de API están vinculadas a su cuenta BNBCalc y deben mantenerse seguras. Incluya su clave de API en el encabezado de la solicitud como se muestra a continuación:

x-bnbcalc-api-key: YOUR_API_KEY

Puede generar claves API desde la página de configuración de su cuenta. Incluya el encabezado x-bnbcalc-api-key en cada solicitud de API para autenticarse.

POST/v1/external/analysis/create/buy

Crear análisis de compra

Crear un nuevo análisis de compra para una propiedad. Requiere detalles de la propiedad, información de la ubicación y precio de compra.

Parámetros de Ubicación (Condicional)

⚠️ Proporcione lat Y lng, O proporcione fullAddress. Se requiere al menos un método.

latnumbercondicional

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)(e.g., -82.6403)

fullAddressstringcondicional

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parámetros Requeridos

purchasePriceUSDnumberrequerido

Precio de compra en USD(e.g., 350000)

bedroomsnumberrequerido

Número de dormitorios(e.g., 3)

bathroomsnumberrequerido

Número de baños(e.g., 2)

accomodatesnumberrequerido

Número de huéspedes que la propiedad puede alojar(e.g., 6)

Parámetros Opcionales

monthlyRentUSDnumberopcional

Alquiler mensual esperado en USD para alquiler a largo plazo(e.g., 2500)

interestRatePercentagenumberopcional

Porcentaje de la tasa de interés (0-15)(e.g., 5.1)

squareFeetnumberopcional

Superficie en pies cuadrados de la propiedad(e.g., 1500)

statestringopcional

Nombre del estado(e.g., Florida)

citystringopcional

Nombre de la ciudad(e.g., St. Petersburg)

countystringopcional

Nombre del condado(e.g., Pinellas County)

postalCodestringopcional

Código postal(e.g., 33703)

countrystringopcional

Nombre del país(e.g., United States)

streetstringopcional

Nombre de la calle(e.g., 2nd Avenue North)

streetNumberstringopcional

Número de casa(e.g., 4935)

unitstringopcional

Número de unidad o apartamento, si corresponde

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Crear análisis de arbitraje

Crea un nuevo análisis de arbitraje (arbitraje de alquiler) para una propiedad. Utiliza los mismos campos obligatorios que el análisis de compra.

Parámetros de Ubicación (Condicional)

⚠️ Proporcione lat Y lng, O proporcione fullAddress. Se requiere al menos un método.

latnumbercondicional

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)(e.g., -82.6403)

fullAddressstringcondicional

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parámetros Requeridos

monthlyRentUSDnumberrequerido

Alquiler mensual esperado en USD para alquiler a largo plazo(e.g., 2500)

bedroomsnumberrequerido

Número de dormitorios(e.g., 3)

bathroomsnumberrequerido

Número de baños(e.g., 2)

accomodatesnumberrequerido

Número de huéspedes que la propiedad puede alojar(e.g., 6)

Parámetros Opcionales

purchasePriceUSDnumberopcional

Precio de compra en USD(e.g., 350000)

squareFeetnumberopcional

Superficie en pies cuadrados de la propiedad(e.g., 1500)

statestringopcional

Nombre del estado(e.g., Florida)

citystringopcional

Nombre de la ciudad(e.g., St. Petersburg)

countystringopcional

Nombre del condado(e.g., Pinellas County)

postalCodestringopcional

Código postal(e.g., 33703)

countrystringopcional

Nombre del país(e.g., United States)

streetstringopcional

Nombre de la calle(e.g., 2nd Avenue North)

streetNumberstringopcional

Número de casa(e.g., 4935)

unitstringopcional

Número de unidad o apartamento, si corresponde

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Crear análisis propio

Crear un nuevo análisis de propiedad propia. Utiliza los mismos campos obligatorios que el análisis de compra.

Parámetros de Ubicación (Condicional)

⚠️ Proporcione lat Y lng, O proporcione fullAddress. Se requiere al menos un método.

latnumbercondicional

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)(e.g., -82.6403)

fullAddressstringcondicional

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parámetros Requeridos

purchasePriceUSDnumberrequerido

Precio de compra en USD(e.g., 350000)

downPaymentPercentagenumberrequerido

Porcentaje de pago inicial (0-40)(e.g., 20)

interestRatePercentagenumberrequerido

Porcentaje de la tasa de interés (0-15)(e.g., 5.1)

mortgageLengthnumberrequerido

Plazo de hipoteca en años (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberrequerido

Años restantes de la hipoteca (No puede ser mayor que la duración de la hipoteca)

bedroomsnumberrequerido

Número de dormitorios(e.g., 3)

bathroomsnumberrequerido

Número de baños(e.g., 2)

accomodatesnumberrequerido

Número de huéspedes que la propiedad puede alojar(e.g., 6)

Parámetros Opcionales

monthlyRentUSDnumberopcional

Alquiler mensual esperado en USD para alquiler a largo plazo(e.g., 2500)

squareFeetnumberopcional

Superficie en pies cuadrados de la propiedad(e.g., 1500)

statestringopcional

Nombre del estado(e.g., Florida)

citystringopcional

Nombre de la ciudad(e.g., St. Petersburg)

countystringopcional

Nombre del condado(e.g., Pinellas County)

postalCodestringopcional

Código postal(e.g., 33703)

countrystringopcional

Nombre del país(e.g., United States)

streetstringopcional

Nombre de la calle(e.g., 2nd Avenue North)

streetNumberstringopcional

Número de casa(e.g., 4935)

unitstringopcional

Número de unidad o apartamento, si corresponde

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Crear análisis de Cohost

Crear historial de coanfitriones

Parámetros de Ubicación (Condicional)

⚠️ Proporcione lat Y lng, O proporcione fullAddress. Se requiere al menos un método.

latnumbercondicional

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)(e.g., -82.6403)

fullAddressstringcondicional

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parámetros Requeridos

bedroomsnumberrequerido

Número de dormitorios(e.g., 3)

bathroomsnumberrequerido

Número de baños(e.g., 2)

accomodatesnumberrequerido

Número de huéspedes que la propiedad puede alojar(e.g., 6)

Parámetros Opcionales

cohostCommissionPercentagenumberopcional

Porcentaje de comisión del coanfitrión(e.g., 10)

squareFeetnumberopcional

Superficie en pies cuadrados de la propiedad(e.g., 1500)

statestringopcional

Nombre del estado(e.g., Florida)

citystringopcional

Nombre de la ciudad(e.g., St. Petersburg)

countystringopcional

Nombre del condado(e.g., Pinellas County)

postalCodestringopcional

Código postal(e.g., 33703)

countrystringopcional

Nombre del país(e.g., United States)

streetstringopcional

Nombre de la calle(e.g., 2nd Avenue North)

streetNumberstringopcional

Número de casa(e.g., 4935)

unitstringopcional

Número de unidad o apartamento, si corresponde

Solicitud de ejemplo

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

Respuesta de ejemplo

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

Códigos de error

La API BNBCalc utiliza códigos de estado de respuesta HTTP estándar para indicar el éxito o fracaso de las solicitudes de API. Las solicitudes exitosas devuelven códigos 2xx, mientras que los errores devuelven códigos 4xx o 5xx con información de error adicional en el cuerpo de la respuesta.

200

Éxito

400

Solicitud incorrecta - Parámetros inválidos

401

No autorizado - Clave API inválida

429

Demasiadas solicitudes - Límite de peticiones excedido

500

Error interno del servidor