Documentación de la API de datos de Airbnb

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.

Especificación OpenAPI
URL base
https://atlas.bnbcalc.com
Encabezado de clave API
x-bnbcalc-api-key
Servidor MCP
https://atlas.bnbcalc.com/mcp
Actualizado

Primeros pasos

  1. 1

    Crea una cuenta en BNBCalc y genera una clave de API en la configuración de tu panel.

  2. 2

    Envía tu clave en la cabecera x-bnbcalc-api-key en cada solicitud.

  3. 3

    POST a property's location and details to any analysis endpoint and read the JSON response, including the hosted report URL.

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.

Importa la descripción de OpenAPI 3.1 en Postman, Insomnia o un generador de clientes: https://www.bnbcalc.com/developers/openapi.json

No escribe código? Use BNBCalc de Claude, ChatGPT u otra aplicación de IA en su lugar. Guía de configuración de MCP

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:

HTTP

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.

Crear análisis

  • 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.
  • Cuando un paso de IA no se puede completar, la respuesta aún devuelve 201 con el análisis válido y una matriz de advertencias que explica lo que se omitió. Verifique las advertencias en lugar de asumir que los resultados de la IA siempre están presentes.
  • Cada paso de IA completado agrega $0.10 a la llamada. Los pasos de IA que fallan o caducan nunca se cobran, y /enhance solo se factura por los pasos de IA que se completaron, sin una tarifa base por llamada.

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.

Herramienta MCPcreate_buy_analysis

Parámetros de Ubicación (Condicional)

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

latnumber

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)

Ejemplo: 27.7676

lngnumber

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)

Ejemplo: -82.6403

fullAddressstring

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)

Ejemplo: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parámetros Requeridos

purchasePriceUSDnumber

Precio de compra en USD

Ejemplo: 350000

bedroomsnumber

Número de dormitorios

Ejemplo: 3

bathroomsnumber

Número de baños

Ejemplo: 2

accomodatesnumber

Número de huéspedes que la propiedad puede alojar

Ejemplo: 6

Parámetros Opcionales

monthlyRentUSDnumber

Alquiler mensual esperado en USD para alquiler a largo plazo

Ejemplo: 2500

interestRatePercentagenumber

Porcentaje de la tasa de interés (0-15)

Ejemplo: 5.1

downPaymentPercentagenumber

Porcentaje de pago inicial (0-40)

Ejemplo: 25

mortgageLengthnumber

Plazo de hipoteca en años (0-30)

Ejemplo: 15

squareFeetnumber

Superficie en pies cuadrados de la propiedad

Ejemplo: 1500

statestring

Nombre del estado

Ejemplo: Florida

citystring

Nombre de la ciudad

Ejemplo: St. Petersburg

countystring

Nombre del condado

Ejemplo: Pinellas County

postalCodestring

Código postal

Ejemplo: 33703

countrystring

Nombre del país

Ejemplo: United States

streetstring

Nombre de la calle

Ejemplo: 2nd Avenue North

streetNumberstring

Número de casa

Ejemplo: 4935

unitstring

Número de unidad o apartamento, si corresponde

addAICompsboolean

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

Ejemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Ejemplo: true

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

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,
    "yearOnePrincipalPaidUSD": 5635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
    "revenueBasis": "full_time_potential",
    "actualAnnualRevenue": {
      "p25": 24180,
      "p50": 36920,
      "p75": 47350,
      "p90": 58810,
      "average": 37640
    }
  }
}

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.

latnumber

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)

Ejemplo: 27.7676

lngnumber

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)

Ejemplo: -82.6403

fullAddressstring

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)

Ejemplo: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parámetros Requeridos

monthlyRentUSDnumber

Alquiler mensual esperado en USD para alquiler a largo plazo

Ejemplo: 2500

bedroomsnumber

Número de dormitorios

Ejemplo: 3

bathroomsnumber

Número de baños

Ejemplo: 2

accomodatesnumber

Número de huéspedes que la propiedad puede alojar

Ejemplo: 6

Parámetros Opcionales

purchasePriceUSDnumber

Precio de compra en USD

Ejemplo: 350000

squareFeetnumber

Superficie en pies cuadrados de la propiedad

Ejemplo: 1500

statestring

Nombre del estado

Ejemplo: Florida

citystring

Nombre de la ciudad

Ejemplo: St. Petersburg

countystring

Nombre del condado

Ejemplo: Pinellas County

postalCodestring

Código postal

Ejemplo: 33703

countrystring

Nombre del país

Ejemplo: United States

streetstring

Nombre de la calle

Ejemplo: 2nd Avenue North

streetNumberstring

Número de casa

Ejemplo: 4935

unitstring

Número de unidad o apartamento, si corresponde

addAICompsboolean

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

Ejemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Ejemplo: true

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

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.

Herramienta MCPcreate_owned_analysis

Parámetros de Ubicación (Condicional)

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

latnumber

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)

Ejemplo: 27.7676

lngnumber

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)

Ejemplo: -82.6403

fullAddressstring

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)

Ejemplo: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parámetros Requeridos

purchasePriceUSDnumber

Precio de compra en USD

Ejemplo: 350000

downPaymentPercentagenumber

Porcentaje de pago inicial (0-40)

Ejemplo: 20

interestRatePercentagenumber

Porcentaje de la tasa de interés (0-15)

Ejemplo: 5.1

mortgageLengthnumber

Plazo de hipoteca en años (0-30)

Ejemplo: 30

yearsRemainingOnMortgagenumber

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

bedroomsnumber

Número de dormitorios

Ejemplo: 3

bathroomsnumber

Número de baños

Ejemplo: 2

accomodatesnumber

Número de huéspedes que la propiedad puede alojar

Ejemplo: 6

Parámetros Opcionales

monthlyRentUSDnumber

Alquiler mensual esperado en USD para alquiler a largo plazo

Ejemplo: 2500

squareFeetnumber

Superficie en pies cuadrados de la propiedad

Ejemplo: 1500

statestring

Nombre del estado

Ejemplo: Florida

citystring

Nombre de la ciudad

Ejemplo: St. Petersburg

countystring

Nombre del condado

Ejemplo: Pinellas County

postalCodestring

Código postal

Ejemplo: 33703

countrystring

Nombre del país

Ejemplo: United States

streetstring

Nombre de la calle

Ejemplo: 2nd Avenue North

streetNumberstring

Número de casa

Ejemplo: 4935

unitstring

Número de unidad o apartamento, si corresponde

addAICompsboolean

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

Ejemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Ejemplo: true

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

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,
    "yearOnePrincipalPaidUSD": 5635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
    "revenueBasis": "full_time_potential",
    "actualAnnualRevenue": {
      "p25": 24180,
      "p50": 36920,
      "p75": 47350,
      "p90": 58810,
      "average": 37640
    }
  }
}

POST /v1/external/analysis/create/cohost

Crear análisis de Cohost

Crear historial de coanfitriones

Herramienta MCPcreate_cohost_analysis

Parámetros de Ubicación (Condicional)

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

latnumber

Coordenada de latitud (debe proporcionarse con lng si no se usa fullAddress)

Ejemplo: 27.7676

lngnumber

Coordenada de longitud (debe proporcionarse con lat si no se usa fullAddress)

Ejemplo: -82.6403

fullAddressstring

Dirección completa de la propiedad (puede usarse en lugar de coordenadas lat/lng)

Ejemplo: 4935 2nd Avenue North, St. Petersburg, FL 33703

Parámetros Requeridos

bedroomsnumber

Número de dormitorios

Ejemplo: 3

bathroomsnumber

Número de baños

Ejemplo: 2

accomodatesnumber

Número de huéspedes que la propiedad puede alojar

Ejemplo: 6

Parámetros Opcionales

cohostCommissionPercentagenumber

Porcentaje de comisión del coanfitrión

Ejemplo: 10

squareFeetnumber

Superficie en pies cuadrados de la propiedad

Ejemplo: 1500

statestring

Nombre del estado

Ejemplo: Florida

citystring

Nombre de la ciudad

Ejemplo: St. Petersburg

countystring

Nombre del condado

Ejemplo: Pinellas County

postalCodestring

Código postal

Ejemplo: 33703

countrystring

Nombre del país

Ejemplo: United States

streetstring

Nombre de la calle

Ejemplo: 2nd Avenue North

streetNumberstring

Número de casa

Ejemplo: 4935

unitstring

Número de unidad o apartamento, si corresponde

addAICompsboolean

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

Ejemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Ejemplo: true

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

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

Enriquecimiento con IA

POST /v1/external/analysis/enhance

Mejorar análisis con IA

Ejecuta el enriquecimiento de IA sobre un análisis que ya creaste y devuelve el análisis recalculado. Úsalo cuando quieras que se apliquen comparables seleccionados por IA o estimaciones de gastos de IA a posteriori, o cuando prefieras mantener la llamada de creación original rápida.

Herramienta MCPenhance_analysis
  • 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.
  • Cuando un paso de IA no se puede completar, la respuesta aún devuelve 201 con el análisis válido y una matriz de advertencias que explica lo que se omitió. Verifique las advertencias en lugar de asumir que los resultados de la IA siempre están presentes.
  • Cada paso de IA completado agrega $0.10 a la llamada. Los pasos de IA que fallan o caducan nunca se cobran, y /enhance solo se factura por los pasos de IA que se completaron, sin una tarifa base por llamada.
  • Si cada paso de IA que solicitó falla, la llamada es gratuita y la respuesta contiene solo advertencias, sin datos. Su análisis almacenado no cambia en ese caso, por lo que la copia que ya tiene sigue siendo actual. Los puntos de conexión de creación siempre devuelven datos, ya que su tarifa base cubre el informe en sí.

Parámetros Requeridos

analysisIdstring

The _id of an analysis previously created with your API key

Ejemplo: 000000000000000000000000

Parámetros Opcionales

addAICompsboolean

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

Ejemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

Ejemplo: true

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

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 IA es opcional por solicitud a través de addAIComps y addAIExpenseEstimates, y cada paso de IA tiene un límite de tiempo y falla de forma abierta. Una solicitud que solicitó IA aún devuelve 201 con un análisis completo y totalmente recalculado; cualquier cosa que no se pudo ejecutar se informa en la matriz de advertencias de nivel superior en lugar de generar un error.

Tiempos de espera y límites de tasa

  • El trabajo de IA tiene un presupuesto de 90 segundos medido desde el inicio de la solicitud, no desde el momento en que comienza el paso de IA, por lo que la geocodificación y la creación de análisis cuentan para ello. Cuando se agota el presupuesto, el análisis se devuelve sin el paso de IA incompleto y 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 IA omitido, llama a POST /v1/external/analysis/enhance con el mismo analysisId en lugar de crear el análisis nuevamente. Enhance no tiene costo base de llamada, por lo que un reintento solo cuesta los pasos de IA que se completan.

Advertencias de respuesta

Una respuesta 201 aún puede contener una matriz de advertencias. Trátela como el registro de lo que no se ejecutó y verifíquela antes de asumir que los resultados de la IA 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 utilizables de las fichas para la dirección no estuvieron listas a tiempo: no se encontró ninguna, muy pocas fueron 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 volver a intentarlo con /enhance poco después suele tener éxito.
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 estaba disponible. Esto es transitorio, así que intente nuevamente 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 IA de comparables ya está trabajando en este análisis. Espere antes de volver a intentarlo: la ejecución mantiene un bloqueo hasta por 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 estaba disponible. Esto es transitorio, así que intente nuevamente 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 paso de IA completado agrega $0.10 a la llamada. Los pasos que caducan, fallan o recurren a la proyección existente no se facturan (aiComps.applied establecido en false significa que las comparaciones de IA no se facturaron), y una llamada /enhance donde se omitió cada paso solicitado no se factura en absoluto.

Límites de tasa

Los límites cuentan por IP del llamador, a menos que una fila diga lo contrario. Las respuestas limitadas llevan X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una solicitud que excede un límite devuelve 429 con una cabecera Retry-After en segundos y nunca se factura, así que espere ese tiempo antes de reintentar.

100 por segundo
Cada ruta /v1/external.
5 por minuto
POST /v1/external/analysis/enhance y ejecuciones de Listing Optimizer (run_listing_optimization).
10 por minuto
Solicitudes que establecen addAIComps o addAIExpenseEstimates, por clave de API, con un máximo de 2 en curso.
10 a 60 por minuto
Listados en vivo 10; detalles de la propiedad, estimaciones de alquiler y cuenta 30; horas de participación material de registro 60.
2.000 por día
Búsquedas de datos (estimaciones de ingresos, tarifas por noche, comparables, listados y fotos, listados en vivo, detalles de la propiedad y estimaciones de alquiler) por cuenta, compartidas por la API REST y el servidor MCP, y hasta 2500 filas de listados al día. El límite se restablece a las 00:00 UTC.

Códigos de error

La API de BNBCalc usa códigos de estado HTTP estándar para indicar el éxito o el fallo de las solicitudes. Las solicitudes correctas devuelven códigos 2xx, mientras que los errores devuelven códigos 4xx o 5xx con información adicional en el cuerpo de la respuesta. Las solicitudes fallidas (4xx o 5xx) nunca se cobran.

201
Creado: el análisis se creó o mejoró y está en la respuesta
400
Solicitud incorrecta - Parámetros inválidos
401
No autorizado - Clave API inválida
402
Payment Required - La cuenta de la clave no tiene una suscripción de API activa o no le quedan créditos de Listing Optimizer
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - No se encontró el análisis, el anuncio o la ubicación solicitados
409
Conflict - Ya hay una ejecución de IA o de Listing Optimizer en curso, el análisis cambió desde que lo leíste o el informe aún no está listo
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 - Un modelo de IA o la fuente de anuncios no está disponible temporalmente; inténtalo más tarde
Ver estado de la API

Guías de la API

Precios de la API

Vea lo que cuesta la API de BNBCalc: $0 al mes, $0.20 por informe y $0.10 por cada paso de IA completado.

Casos de uso de la API

Descubre cómo plataformas PropTech, inversores, prestamistas, operadores y analistas usan la API en flujos de trabajo de producción.

Cobertura de datos

Comprende la cobertura de propiedades internacionales, estimaciones basadas en comparables, entradas de ubicación y dónde encaja la API.

Comparación de APIs

Vea cómo la API de BNBCalc se compara con la API de AirDNA y otras APIs de datos de Airbnb en cuanto a acceso, modelo de precios y resultados.

Hojas de cálculo de Google

Analice una lista de direcciones en Hojas de cálculo de Google con un breve Apps Script.

Servidor MCP

Conecte Claude, Cursor o VS Code a BNBCalc y ejecute estimaciones de ingresos y análisis de acuerdos desde su asistente de IA.

Guía de configuración de MCP

Conecta Claude, ChatGPT, Claude Code, Cursor o VS Code al servidor MCP, paso a paso.

Referencia MCP

Cómo se autentica el servidor MCP, cada herramienta con su precio, la aprobación de herramientas de pago y los límites.

Registro de cambios

Qué ha cambiado en la API REST y el servidor MCP, lo más reciente primero.

Estado

Comprobaciones en vivo de la API REST y del servidor MCP.