Documentação da API de Dados do Airbnb

Bem-vindo à API do BNBCalc. Esta documentação ajuda você a integrar a análise de propriedades de aluguel de curto prazo em seu aplicativo.

Use a API de Dados do Airbnb do BNBCalc para obter receita de propriedade, ocupação, ADR, listagens comparáveis ativas do Airbnb, percentis, métricas de investimento e URLs de relatórios hospedados para aplicativos, relatórios, subscrição e ferramentas de gestão.

Primeiros Passos

Para começar a usar a API de Dados do Airbnb do BNBCalc, você precisará de:

1. Crie uma conta BNBCalc ou faça login na sua conta existente

2. Navegue até as configurações da sua conta para gerar uma chave de API

3. Inclua sua chave de API em todas as requisições da API utilizando o cabeçalho x-bnbcalc-api-key.

4. Comece a fazer solicitações para acessar dados e análises de imóveis.

Todos os endpoints da API usam HTTPS e retornam respostas em JSON. Mantenha as chaves da API em seu servidor, não no código do cliente do navegador ou móvel. As rotas da API externa estão atualmente limitadas a 100 solicitações por segundo e usam códigos de resposta HTTP padrão para indicar sucesso ou falha.

Autenticação

Todas as solicitações da API requerem autenticação usando uma chave da API. As chaves da API estão vinculadas à sua conta do BNBCalc, devem ser mantidas do lado do servidor e nunca devem ser expostas no código do frontend. Inclua sua chave da API no cabeçalho da solicitação como mostrado abaixo:

x-bnbcalc-api-key: YOUR_API_KEY

Você pode gerar chaves da API de forma autônoma na página de configurações da sua conta. Inclua o cabeçalho x-bnbcalc-api-key em cada solicitação da API para autenticar.

POST/v1/external/analysis/create/buy

Criar Análise de Compra

Criar uma nova análise de compra para um imóvel. Requer detalhes do imóvel, informações sobre a localização e preço 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 Localização (Condicional)

⚠️ Forneça lat E lng, OU forneça fullAddress. Pelo menos um método é obrigatório.

latnumbercondicional

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)(e.g., -82.6403)

fullAddressstringcondicional

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parâmetros Obrigatórios

purchasePriceUSDnumberobrigatório

Preço de compra em USD(e.g., 350000)

bedroomsnumberobrigatório

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

bathroomsnumberobrigatório

Número de banheiros(e.g., 2)

accomodatesnumberobrigatório

Número de hóspedes que a propriedade pode acomodar(e.g., 6)

Parâmetros Opcionais

monthlyRentUSDnumberopcional

Aluguel mensal esperado em USD para aluguel de longo prazo(e.g., 2500)

interestRatePercentagenumberopcional

Taxa de juro em percentagem (0-15)(e.g., 5.1)

squareFeetnumberopcional

Área em pés quadrados do imóvel(e.g., 1500)

statestringopcional

Nome do estado(e.g., Florida)

citystringopcional

Nome da cidade(e.g., St. Petersburg)

countystringopcional

Nome do condado(e.g., Pinellas County)

postalCodestringopcional

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

countrystringopcional

Nome do país(e.g., United States)

streetstringopcional

Nome da rua(e.g., 2nd Avenue North)

streetNumberstringopcional

Número da rua(e.g., 4935)

unitstringopcional

Número da unidade/apartamento, se aplicável

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)

Exemplo de solicitação

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

Resposta de exemplo

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

Criar análise de arbitragem

Crie uma nova análise de arbitragem (arbitragem de aluguel) para uma propriedade. Usa os mesmos campos obrigatórios que a análise de compra.

Parâmetros de Localização (Condicional)

⚠️ Forneça lat E lng, OU forneça fullAddress. Pelo menos um método é obrigatório.

latnumbercondicional

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)(e.g., -82.6403)

fullAddressstringcondicional

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parâmetros Obrigatórios

monthlyRentUSDnumberobrigatório

Aluguel mensal esperado em USD para aluguel de longo prazo(e.g., 2500)

bedroomsnumberobrigatório

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

bathroomsnumberobrigatório

Número de banheiros(e.g., 2)

accomodatesnumberobrigatório

Número de hóspedes que a propriedade pode acomodar(e.g., 6)

Parâmetros Opcionais

purchasePriceUSDnumberopcional

Preço de compra em USD(e.g., 350000)

squareFeetnumberopcional

Área em pés quadrados do imóvel(e.g., 1500)

statestringopcional

Nome do estado(e.g., Florida)

citystringopcional

Nome da cidade(e.g., St. Petersburg)

countystringopcional

Nome do condado(e.g., Pinellas County)

postalCodestringopcional

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

countrystringopcional

Nome do país(e.g., United States)

streetstringopcional

Nome da rua(e.g., 2nd Avenue North)

streetNumberstringopcional

Número da rua(e.g., 4935)

unitstringopcional

Número da unidade/apartamento, se aplicável

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)

Exemplo de solicitação

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

Resposta de exemplo

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

Criar análise própria

Crie uma nova análise de imóvel próprio. Utiliza os mesmos campos obrigatórios da análise de compra.

Parâmetros de Localização (Condicional)

⚠️ Forneça lat E lng, OU forneça fullAddress. Pelo menos um método é obrigatório.

latnumbercondicional

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)(e.g., -82.6403)

fullAddressstringcondicional

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parâmetros Obrigatórios

purchasePriceUSDnumberobrigatório

Preço de compra em USD(e.g., 350000)

downPaymentPercentagenumberobrigatório

Percentual de entrada (0-40)(e.g., 20)

interestRatePercentagenumberobrigatório

Taxa de juro em percentagem (0-15)(e.g., 5.1)

mortgageLengthnumberobrigatório

Prazo da hipoteca em anos (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberobrigatório

Anos restantes na hipoteca (Não pode ser maior que o prazo da hipoteca)

bedroomsnumberobrigatório

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

bathroomsnumberobrigatório

Número de banheiros(e.g., 2)

accomodatesnumberobrigatório

Número de hóspedes que a propriedade pode acomodar(e.g., 6)

Parâmetros Opcionais

monthlyRentUSDnumberopcional

Aluguel mensal esperado em USD para aluguel de longo prazo(e.g., 2500)

squareFeetnumberopcional

Área em pés quadrados do imóvel(e.g., 1500)

statestringopcional

Nome do estado(e.g., Florida)

citystringopcional

Nome da cidade(e.g., St. Petersburg)

countystringopcional

Nome do condado(e.g., Pinellas County)

postalCodestringopcional

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

countrystringopcional

Nome do país(e.g., United States)

streetstringopcional

Nome da rua(e.g., 2nd Avenue North)

streetNumberstringopcional

Número da rua(e.g., 4935)

unitstringopcional

Número da unidade/apartamento, se aplicável

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)

Exemplo de solicitação

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

Resposta de exemplo

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

Criar análise Cohost

Criar histórico de coanfitriões

Parâmetros de Localização (Condicional)

⚠️ Forneça lat E lng, OU forneça fullAddress. Pelo menos um método é obrigatório.

latnumbercondicional

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)(e.g., 27.7676)

lngnumbercondicional

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)(e.g., -82.6403)

fullAddressstringcondicional

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Parâmetros Obrigatórios

bedroomsnumberobrigatório

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

bathroomsnumberobrigatório

Número de banheiros(e.g., 2)

accomodatesnumberobrigatório

Número de hóspedes que a propriedade pode acomodar(e.g., 6)

Parâmetros Opcionais

cohostCommissionPercentagenumberopcional

Percentual de comissão do coanfitrião(e.g., 10)

squareFeetnumberopcional

Área em pés quadrados do imóvel(e.g., 1500)

statestringopcional

Nome do estado(e.g., Florida)

citystringopcional

Nome da cidade(e.g., St. Petersburg)

countystringopcional

Nome do condado(e.g., Pinellas County)

postalCodestringopcional

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

countrystringopcional

Nome do país(e.g., United States)

streetstringopcional

Nome da rua(e.g., 2nd Avenue North)

streetNumberstringopcional

Número da rua(e.g., 4935)

unitstringopcional

Número da unidade/apartamento, se aplicável

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)

Exemplo de solicitação

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

Resposta de exemplo

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

Se todas as funções de IA solicitadas falharem, a chamada é gratuita e a resposta contém apenas warnings — sem data. Nesse caso a sua análise guardada permanece inalterada, pelo que a cópia que já tem continua atual. Os endpoints de criação devolvem sempre data, porque a sua taxa base cobre o próprio relatório.

Parâmetros Obrigatórios

analysisIdstringobrigatório

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

Parâmetros Opcionais

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)

Exemplo de solicitação

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

Resposta de exemplo

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

Comportamento do enriquecimento por AI

O enriquecimento por AI é opcional por requisição através de addAIComps e addAIExpenseEstimates, e cada etapa de AI tem limite de tempo e falha aberta. Uma requisição que solicitou AI ainda retorna 200 com uma análise completa e totalmente recalculada; qualquer coisa que não pôde ser executada é reportada no array de nível superior 'warnings' em vez de gerar um erro.

Tempos limite e limites de taxa

O trabalho de AI tem um orçamento de 90 segundos medido desde o início da requisição, não desde o momento em que a etapa de AI começa — geocodificação e criação da análise contam contra esse orçamento. Quando o orçamento se esgota, a análise é retornada sem a etapa de AI inacabada e um aviso de timeout é incluído.

Configure o timeout do seu cliente para pelo menos 300 segundos. A maioria das chamadas de AI retorna bem dentro do orçamento, mas um cliente que aborta antes do deadline do servidor transforma uma análise concluída e faturável em uma resposta perdida.

Uma chamada ao modelo precisa de pelo menos 45 segundos de orçamento restante para iniciar. Uma requisição que gasta a maior parte do orçamento aguardando fotos do anúncio retorna ai_comps_timed_out sem chamar o modelo em vez de iniciar uma execução que não pode terminar.

Requisições que ativam uma flag de AI são limitadas por chave de API: 10 por minuto, com no máximo 2 em andamento simultaneamente. Ultrapassar qualquer limite retorna 429 com um cabeçalho Retry-After, e X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset são definidos em cada requisição de AI. Chamadas sem flag de AI não são afetadas por esse limite.

Para reenviar uma etapa de AI ignorada, chame POST /v1/external/analysis/enhance com o mesmo analysisId em vez de criar a análise novamente. Enhance não tem taxa base de chamada, então uma nova tentativa custa apenas pelas funções de AI que forem executadas.

Avisos na resposta

Uma resposta 200 ainda pode carregar um array 'warnings'. Trate-o como o registro do que não foi executado e verifique-o antes de assumir que os resultados de AI estão presentes. Cada etapa reportada aqui foi ignorada, e etapas ignoradas nunca são cobradas.

ai_comps_requires_user_scoped_api_key

AI comps requerem uma chave de API vinculada a uma conta de usuário. A chave não pôde ser resolvida para um proprietário, então o seletor de comps nunca foi executado.

ai_comps_unavailable_for_property

AI comps estão disponíveis apenas para propriedades dos Estados Unidos, e a análise armazenada está fora desse escopo.

ai_comps_photos_not_ready

Fotos utilizáveis do anúncio para o endereço não ficaram prontas a tempo — nenhuma foi encontrada, houve fotos insuficientes utilizáveis, ou a galeria ainda estava processando quando o orçamento expirou. Fotos são reunidas em background após a criação da análise, então tentar novamente com /enhance logo depois normalmente funciona.

ai_comps_timed_out

O orçamento de AI se esgotou antes do retorno do modelo, portanto os comparáveis determinísticos e a projeção de receita foram mantidos.

ai_comps_benchmark_fallback

O modelo foi executado mas selecionou comparáveis insuficientes para formar um benchmark, então a projeção de receita existente foi mantida. Nada foi escrito na análise e a etapa não foi cobrada.

ai_comps_model_unavailable

O provedor de modelo estava indisponível. Isso é transitório — tente novamente com /enhance.

ai_comps_already_applied

Esta análise já tem um benchmark de IA válido, pelo que nada foi reexecutado nem cobrado. Editar o imóvel invalida-o e a chamada seguinte é executada de facto.

ai_comps_run_in_progress

Outra execução de AI comps já está a trabalhar nesta análise. Aguarde antes de tentar novamente — a execução mantém um bloqueio até 10 minutos.

ai_comps_analysis_changed

A análise foi editada enquanto o modelo era executado, pelo que o benchmark não foi escrito em vez de substituir os valores mais recentes. Tente novamente com /enhance.

ai_comps_forbidden

A análise não foi criada com esta chave de API, pelo que os AI comps não puderam ser executados sobre ela.

ai_comps_failed

AI comps não puderam ser concluídos por outro motivo. A própria análise é válida e permanece inalterada.

ai_expense_estimates_timed_out

O orçamento de AI se esgotou antes do retorno do estimador de despesas, portanto as despesas operacionais padrão foram mantidas.

ai_expense_estimates_no_proposals

O estimador não gerou propostas de despesas para esta propriedade, então nenhuma despesa operacional foi alterada.

ai_expense_estimates_stale_preview

A análise mudou enquanto a estimativa estava sendo preparada, então ela foi descartada em vez de aplicada a entradas obsoletas. Tente novamente com /enhance.

ai_expense_estimates_model_unavailable

O provedor de modelo estava indisponível. Isso é transitório — tente novamente com /enhance.

ai_expense_estimates_already_applied

Esta análise já tem despesas estimadas por IA, pelo que nada foi reexecutado nem cobrado.

ai_expense_estimates_unavailable_for_property

Nenhum campo de despesas operacionais desta análise era elegível para estimativa por IA, pelo que foram mantidas as despesas predefinidas.

ai_expense_estimates_forbidden

A análise não foi criada com esta chave de API, pelo que as estimativas de despesas por IA não puderam ser executadas sobre ela.

ai_expense_estimates_failed

As estimativas de despesas por AI não puderam ser aplicadas. A análise mantém suas despesas operacionais padrão.

Faça a correspondência pelos prefixos ai_comps_ e ai_expense_estimates_ em vez da string exata: qualquer outro código com esses prefixos significa que essa etapa falhou, não foi aplicada e não foi cobrada.

Resposta de exemplo

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

aiComps.warnings

O array aninhado aiComps.warnings é um sinal diferente do top-level: descreve a qualidade da piscina de comparáveis com que o modelo trabalhou, não uma etapa que falhou. Consulte aiComps.applied para saber se o benchmark de AI foi realmente escrito na análise.

thin_benchmark_pool

Menos de quatro imóveis comparáveis sustentaram o benchmark, então ele se baseia em uma amostra pequena.

no_benchmark_comps

Nenhum imóvel comparável passou na seleção. O benchmark está vazio e a projeção de receita foi mantida inalterada.

ai_benchmark_fallback_to_projected_revenue

Menos de três imóveis comparáveis foram selecionados, então a projeção de receita existente foi mantida em vez do benchmark de AI. Este é o mesmo resultado reportado como ai_comps_benchmark_fallback no nível superior.

minimum_benchmark_pool_backfill

A piscina de benchmark foi preenchida com comparáveis que o modelo não escolheu para atingir a contagem mínima.

Cobrança quando AI é parcial

Cada função de AI que é concluída adiciona $0.10 à chamada. Etapas que expiram por timeout, falham ou recorrem à projeção existente não são cobradas — aiComps.applied definido como false significa que AI comps não foram faturados — e uma chamada /enhance onde todas as etapas solicitadas foram ignoradas não é cobrada.

Códigos de erro

A API do BNBCalc usa códigos de status de resposta HTTP padrão para indicar o sucesso ou a falha das solicitações da API. Relatórios criados com sucesso retornam códigos 2xx, enquanto erros retornam códigos 4xx ou 5xx com informações de erro adicionais no corpo da resposta. Você será cobrado apenas por relatórios criados com sucesso.

200

Sucesso

400

Requisição inválida - Parâmetros inválidos

401

Não autorizado - Chave de 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

Muitas Solicitações - Limite da rota da API externa excedido

500

Erro interno do servidor

502

Bad Gateway - The AI model returned an unusable response

503

Service Unavailable - The AI model is temporarily unavailable