Documentación de la API de datos de Airbnb

Bienvenido a la API de BNBCalc. Esta documentación te ayuda a integrar el análisis de propiedades de alquiler a corto plazo en tu aplicación.

Utiliza la API de datos de Airbnb de BNBCalc para obtener ingresos de propiedades, ocupación, ADR, listados comparables activos de Airbnb, percentiles, métricas de inversión y URLs de informes hospedados para aplicaciones, informes, underwriting y herramientas de gestión.

Primeros pasos

Para comenzar a utilizar la API de datos de Airbnb de 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 JSON. Mantén las claves de API en tu servidor, no en el código de cliente del navegador o móvil. Las rutas de API externas están actualmente limitadas a 100 solicitudes por segundo y utilizan códigos de respuesta HTTP estándar para indicar el éxito o fracaso.

Autenticación

Todas las solicitudes de API requieren autenticación usando una clave de API. Las claves de API están vinculadas a tu cuenta de BNBCalc, deben mantenerse del lado del servidor y nunca deben ser expuestas en el código del frontend. Incluye tu clave de API en el encabezado de la solicitud como se muestra a continuación:

x-bnbcalc-api-key: YOUR_API_KEY

Puedes generar claves de API de forma auto-servicio desde la página de configuración de tu cuenta. Incluye el encabezado x-bnbcalc-api-key en cada solicitud de API para autenticar.

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.

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.

When an AI step cannot complete, the response still returns 200 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.

Each AI function that completes adds $0.10 to the call. AI steps that fail or time out are never charged, and /enhance is billed only for the AI functions that completed — it carries no base call fee.

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

addAICompsbooleanopcional

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.(e.g., true)

addAIExpenseEstimatesbooleanopcional

Estimate operating expenses with AI instead of using category defaults(e.g., true)

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 json
import requests

data = json.loads(r'''{
  "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": "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,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10
  }
}

POST/v1/external/analysis/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

addAICompsbooleanopcional

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.(e.g., true)

addAIExpenseEstimatesbooleanopcional

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Solicitud de ejemplo

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/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 json
import requests

data = json.loads(r'''{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}''')

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/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": "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

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

addAICompsbooleanopcional

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.(e.g., true)

addAIExpenseEstimatesbooleanopcional

Estimate operating expenses with AI instead of using category defaults(e.g., true)

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 json
import requests

data = json.loads(r'''{
  "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": "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,
    "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

addAICompsbooleanopcional

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.(e.g., true)

addAIExpenseEstimatesbooleanopcional

Estimate operating expenses with AI instead of using category defaults(e.g., true)

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 json
import requests

data = json.loads(r'''{
  "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": "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
  }
}

POST/v1/external/analysis/enhance

Enhance Analysis with AI

Runs AI enrichment against an analysis you already created and returns the recalculated analysis. Use this when you want AI-selected comparables or AI expense estimates applied after the fact, or when you would rather keep the original create call fast.

Si fallan todas las funciones de IA solicitadas, la llamada es gratuita y la respuesta contiene solo warnings, sin data. En ese caso su análisis almacenado no cambia, por lo que la copia que ya tiene sigue estando actualizada. Los endpoints de creación siempre devuelven data, porque su tarifa base cubre el propio informe.

Parámetros Requeridos

analysisIdstringrequerido

The _id of an analysis previously created with your API key(e.g., 000000000000000000000000)

Parámetros Opcionales

addAICompsbooleanopcional

Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address.(e.g., true)

addAIExpenseEstimatesbooleanopcional

Estimate operating expenses with AI instead of using category defaults(e.g., true)

Solicitud de ejemplo

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
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/enhance',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "analysisId": "000000000000000000000000",
  "addAIComps": true,
  "addAIExpenseEstimates": true
})
  }
);
const data = await response.json();

import json
import requests

data = json.loads(r'''{
  "analysisId": "000000000000000000000000",
  "addAIComps": true,
  "addAIExpenseEstimates": true
}''')

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

Respuesta de ejemplo

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

Comportamiento del enriquecimiento de AI

El enriquecimiento de AI es opcional por solicitud mediante addAIComps y addAIExpenseEstimates, y cada paso de AI tiene un límite de tiempo y, en caso de fallo, no bloquea la respuesta. Una solicitud que solicitó AI sigue devolviendo 200 con un análisis completo y totalmente recalculado; cualquier cosa que no pudo ejecutarse se informa en el array warnings de nivel superior en lugar de lanzar un error.

Tiempos de espera y límites de tasa

El trabajo de AI dispone de un presupuesto de 90 segundos medido desde el inicio de la petición, no desde el momento en que comienza el paso de AI — la geocodificación y la creación del análisis cuentan dentro de ese presupuesto. Cuando se agota el presupuesto, se devuelve el análisis sin el paso de AI incompleto y con una advertencia de tiempo de espera.

Establezca el tiempo de espera (timeout) de su cliente en al menos 300 segundos. La mayoría de las llamadas AI responden cómodamente dentro del presupuesto, pero un cliente que aborte antes de la propia fecha límite del servidor convierte un análisis completado y facturable en una respuesta perdida.

Una llamada al modelo necesita al menos 45 segundos de presupuesto restante para iniciarse. Una solicitud que gasta la mayor parte de su presupuesto esperando las fotos del anuncio devuelve ai_comps_timed_out sin invocar al modelo, en lugar de iniciar una ejecución que no podría terminar.

Las solicitudes que activan una bandera AI están limitadas por tasa por clave API: 10 por minuto, con un máximo de 2 en vuelo simultáneamente. Superar cualquiera de estos límites devuelve 429 con un encabezado Retry-After, y X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset se establecen en cada solicitud AI. Las llamadas sin la bandera AI no se ven afectadas por este límite.

Para reintentar un paso de AI omitido, llame POST /v1/external/analysis/enhance con el mismo analysisId en lugar de crear el análisis de nuevo. Enhance no tiene tarifa base por llamada, por lo que un reintento solo cuesta las funciones AI que se completen.

Advertencias de respuesta

Una respuesta 200 aún puede incluir un array warnings. Trátelo como el registro de lo que no se ejecutó y revíselo antes de asumir que los resultados de AI están presentes. Cada paso informado aquí fue omitido, y los pasos omitidos nunca se facturan.

ai_comps_requires_user_scoped_api_key

AI comps requieren una clave API vinculada a una cuenta de usuario. No se pudo resolver la clave a un propietario, por lo que el selector de comparables nunca se ejecutó.

ai_comps_unavailable_for_property

AI comps están disponibles solo para propiedades en Estados Unidos, y el análisis almacenado está fuera de ese alcance.

ai_comps_photos_not_ready

Las fotos del anuncio utilizables para la dirección no estuvieron listas a tiempo — no se encontraron, hubo muy pocas utilizables, o la galería aún se estaba procesando cuando se agotó el presupuesto. Las fotos se recopilan en segundo plano después de crear un análisis, por lo que reintentar con /enhance poco después suele funcionar.

ai_comps_timed_out

El presupuesto de AI se agotó antes de que el modelo respondiera, por lo que se conservaron los comparables determinísticos y la proyección de ingresos.

ai_comps_benchmark_fallback

El modelo se ejecutó pero seleccionó muy pocos comparables para formar un benchmark, por lo que se mantuvo la proyección de ingresos existente. No se escribió nada en el análisis y el paso no fue cobrado.

ai_comps_model_unavailable

El proveedor del modelo no estuvo disponible. Esto es transitorio — reintente con /enhance.

ai_comps_already_applied

Este análisis ya tiene un benchmark de IA válido, por lo que no se volvió a ejecutar nada ni se cobró nada. Editar la propiedad lo invalida y la siguiente llamada se ejecuta de verdad.

ai_comps_run_in_progress

Otra ejecución de AI comps ya está trabajando en este análisis. Espere antes de reintentar: la ejecución mantiene un bloqueo de hasta 10 minutos.

ai_comps_analysis_changed

El análisis se editó mientras el modelo se ejecutaba, por lo que el benchmark no se escribió en lugar de sobrescribir los valores más recientes. Reinténtelo con /enhance.

ai_comps_forbidden

El análisis no se creó con esta clave de API, por lo que AI comps no pudo ejecutarse sobre él.

ai_comps_failed

AI comps no pudieron completarse por otra razón. El análisis en sí es válido y no ha cambiado.

ai_expense_estimates_timed_out

El presupuesto de AI se agotó antes de que el estimador de gastos devolviera resultados, por lo que se mantuvieron los gastos operativos predeterminados.

ai_expense_estimates_no_proposals

El estimador no produjo propuestas de gasto para esta propiedad, por lo que no se modificó ningún gasto operativo.

ai_expense_estimates_stale_preview

El análisis cambió mientras se preparaba la estimación, por lo que se descartó en lugar de aplicarse a entradas obsoletas. Reintente con /enhance.

ai_expense_estimates_model_unavailable

El proveedor del modelo no estuvo disponible. Esto es transitorio — reintente con /enhance.

ai_expense_estimates_already_applied

Este análisis ya tiene gastos estimados por IA, por lo que no se volvió a ejecutar nada ni se cobró nada.

ai_expense_estimates_unavailable_for_property

Ningún campo de gastos operativos de este análisis era apto para la estimación con IA, por lo que se mantuvieron sus gastos predeterminados.

ai_expense_estimates_forbidden

El análisis no se creó con esta clave de API, por lo que las estimaciones de gastos con IA no pudieron ejecutarse sobre él.

ai_expense_estimates_failed

No se pudieron aplicar las estimaciones de gastos por AI. El análisis mantiene sus gastos operativos predeterminados.

Coincida por los prefijos ai_comps_ y ai_expense_estimates_ en lugar de la cadena exacta: cualquier otro código con esos prefijos significa que ese paso falló, no se aplicó y no fue cobrado.

Respuesta de ejemplo

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

aiComps.warnings

El array anidado aiComps.warnings es una señal distinta de la del nivel superior: describe la calidad del conjunto de comparables con el que trabajó el modelo, no un paso que falló. Consulte aiComps.applied para saber si el benchmark de AI se escribió realmente en el análisis.

thin_benchmark_pool

Menos de cuatro comparables respaldaron el benchmark, por lo que se basa en una muestra pequeña.

no_benchmark_comps

Ningún comparable pasó la selección. El benchmark está vacío y la proyección de ingresos quedó sin cambios.

ai_benchmark_fallback_to_projected_revenue

Se seleccionaron menos de tres comparables, por lo que se mantuvo la proyección de ingresos existente en lugar del benchmark de AI. Este es el mismo resultado informado como ai_comps_benchmark_fallback a nivel superior.

minimum_benchmark_pool_backfill

El conjunto de benchmark fue rellenado con comparables que el modelo no eligió para alcanzar el recuento mínimo.

Facturación cuando AI es parcial

Cada función AI que se complete añade $0.10 a la llamada. Los pasos que exceden el tiempo de espera, fallan o recurren a la proyección existente no se cobran — aiComps.applied establecido en false significa que AI comps no fueron facturados — y una llamada a /enhance donde todos los pasos solicitados fueron omitidos no se factura en absoluto.

Códigos de error

La API de BNBCalc utiliza códigos de estado de respuesta HTTP estándar para indicar el éxito o fracaso de las solicitudes de API. Los informes creados con éxito devuelven códigos 2xx, mientras que los errores devuelven códigos 4xx o 5xx con información adicional sobre el error en el cuerpo de la respuesta. Solo se te cobrará por los informes creados con éxito.

200

Éxito

400

Solicitud incorrecta - Parámetros inválidos

401

No autorizado - Clave API inválida

403

Forbidden - The analysis does not belong to your API key, or AI estimates are disabled

404

Not Found - No analysis matches the supplied analysisId

409

Conflict - An AI run is already in progress for this analysis, or its values changed mid-request

429

Demasiadas Solicitudes - Límite de ruta de API externa excedido

500

Error interno del servidor

502

Bad Gateway - The AI model returned an unusable response

503

Service Unavailable - The AI model is temporarily unavailable