Documentação da API de Dados do Airbnb

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.

Especificação OpenAPI
URL base
https://atlas.bnbcalc.com
Cabeçalho da chave da API
x-bnbcalc-api-key
Servidor MCP
https://atlas.bnbcalc.com/mcp
Atualizado

Primeiros Passos

  1. 1

    Crie uma conta BNBCalc e gere uma chave de API nas configurações do seu painel.

  2. 2

    Envie sua chave no cabeçalho x-bnbcalc-api-key em cada requisição.

  3. 3

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

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.

Importe a descrição do OpenAPI 3.1 para Postman, Insomnia ou um gerador de cliente: https://www.bnbcalc.com/developers/openapi.json

Não escreve código? Use o BNBCalc do Claude, ChatGPT ou outro aplicativo de IA em vez disso. Guia de configuração MCP

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:

HTTP

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.

Criar análises

  • 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.
  • Quando uma etapa de IA não puder ser concluída, a resposta ainda retornará 201 com a análise válida e uma matriz de avisos explicando o que foi omitido. Verifique os avisos em vez de assumir que os resultados da IA estão sempre presentes.
  • Cada etapa de IA concluída adiciona US$ 0,10 à chamada. Etapas de IA que falham ou expiram nunca são cobradas, e /enhance é cobrado apenas pelas etapas de IA que foram concluídas, sem taxa base por chamada.

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.

Ferramenta MCPcreate_buy_analysis

Parâmetros de Localização (Condicional)

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

latnumber

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)

Exemplo: 27.7676

lngnumber

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)

Exemplo: -82.6403

fullAddressstring

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)

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

Parâmetros Obrigatórios

purchasePriceUSDnumber

Preço de compra em USD

Exemplo: 350000

bedroomsnumber

Número de quartos

Exemplo: 3

bathroomsnumber

Número de banheiros

Exemplo: 2

accomodatesnumber

Número de hóspedes que a propriedade pode acomodar

Exemplo: 6

Parâmetros Opcionais

monthlyRentUSDnumber

Aluguel mensal esperado em USD para aluguel de longo prazo

Exemplo: 2500

interestRatePercentagenumber

Taxa de juro em percentagem (0-15)

Exemplo: 5.1

downPaymentPercentagenumber

Percentual de entrada (0-40)

Exemplo: 25

mortgageLengthnumber

Prazo da hipoteca em anos (0-30)

Exemplo: 15

squareFeetnumber

Área em pés quadrados do imóvel

Exemplo: 1500

statestring

Nome do estado

Exemplo: Florida

citystring

Nome da cidade

Exemplo: St. Petersburg

countystring

Nome do condado

Exemplo: Pinellas County

postalCodestring

Código postal

Exemplo: 33703

countrystring

Nome do país

Exemplo: United States

streetstring

Nome da rua

Exemplo: 2nd Avenue North

streetNumberstring

Número da rua

Exemplo: 4935

unitstring

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

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.

Exemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

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.

latnumber

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)

Exemplo: 27.7676

lngnumber

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)

Exemplo: -82.6403

fullAddressstring

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)

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

Parâmetros Obrigatórios

monthlyRentUSDnumber

Aluguel mensal esperado em USD para aluguel de longo prazo

Exemplo: 2500

bedroomsnumber

Número de quartos

Exemplo: 3

bathroomsnumber

Número de banheiros

Exemplo: 2

accomodatesnumber

Número de hóspedes que a propriedade pode acomodar

Exemplo: 6

Parâmetros Opcionais

purchasePriceUSDnumber

Preço de compra em USD

Exemplo: 350000

squareFeetnumber

Área em pés quadrados do imóvel

Exemplo: 1500

statestring

Nome do estado

Exemplo: Florida

citystring

Nome da cidade

Exemplo: St. Petersburg

countystring

Nome do condado

Exemplo: Pinellas County

postalCodestring

Código postal

Exemplo: 33703

countrystring

Nome do país

Exemplo: United States

streetstring

Nome da rua

Exemplo: 2nd Avenue North

streetNumberstring

Número da rua

Exemplo: 4935

unitstring

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

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.

Exemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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.

Ferramenta MCPcreate_owned_analysis

Parâmetros de Localização (Condicional)

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

latnumber

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)

Exemplo: 27.7676

lngnumber

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)

Exemplo: -82.6403

fullAddressstring

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)

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

Parâmetros Obrigatórios

purchasePriceUSDnumber

Preço de compra em USD

Exemplo: 350000

downPaymentPercentagenumber

Percentual de entrada (0-40)

Exemplo: 20

interestRatePercentagenumber

Taxa de juro em percentagem (0-15)

Exemplo: 5.1

mortgageLengthnumber

Prazo da hipoteca em anos (0-30)

Exemplo: 30

yearsRemainingOnMortgagenumber

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

bedroomsnumber

Número de quartos

Exemplo: 3

bathroomsnumber

Número de banheiros

Exemplo: 2

accomodatesnumber

Número de hóspedes que a propriedade pode acomodar

Exemplo: 6

Parâmetros Opcionais

monthlyRentUSDnumber

Aluguel mensal esperado em USD para aluguel de longo prazo

Exemplo: 2500

squareFeetnumber

Área em pés quadrados do imóvel

Exemplo: 1500

statestring

Nome do estado

Exemplo: Florida

citystring

Nome da cidade

Exemplo: St. Petersburg

countystring

Nome do condado

Exemplo: Pinellas County

postalCodestring

Código postal

Exemplo: 33703

countrystring

Nome do país

Exemplo: United States

streetstring

Nome da rua

Exemplo: 2nd Avenue North

streetNumberstring

Número da rua

Exemplo: 4935

unitstring

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

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.

Exemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

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.

latnumber

Coordenada de latitude (deve ser fornecida com lng se fullAddress não for usado)

Exemplo: 27.7676

lngnumber

Coordenada de longitude (deve ser fornecida com lat se fullAddress não for usado)

Exemplo: -82.6403

fullAddressstring

Endereço completo da propriedade (pode ser usado no lugar das coordenadas lat/lng)

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

Parâmetros Obrigatórios

bedroomsnumber

Número de quartos

Exemplo: 3

bathroomsnumber

Número de banheiros

Exemplo: 2

accomodatesnumber

Número de hóspedes que a propriedade pode acomodar

Exemplo: 6

Parâmetros Opcionais

cohostCommissionPercentagenumber

Percentual de comissão do coanfitrião

Exemplo: 10

squareFeetnumber

Área em pés quadrados do imóvel

Exemplo: 1500

statestring

Nome do estado

Exemplo: Florida

citystring

Nome da cidade

Exemplo: St. Petersburg

countystring

Nome do condado

Exemplo: Pinellas County

postalCodestring

Código postal

Exemplo: 33703

countrystring

Nome do país

Exemplo: United States

streetstring

Nome da rua

Exemplo: 2nd Avenue North

streetNumberstring

Número da rua

Exemplo: 4935

unitstring

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

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.

Exemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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

Enriquecimento de IA

POST /v1/external/analysis/enhance

Melhorar Análise com IA

Executa o enriquecimento de IA em uma análise que você já criou e retorna a análise recalculada. Use isso quando quiser que comparáveis selecionados por IA ou estimativas de despesas de IA sejam aplicados posteriormente, ou quando preferir manter a chamada de criação original rápida.

Ferramenta 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.
  • Quando uma etapa de IA não puder ser concluída, a resposta ainda retornará 201 com a análise válida e uma matriz de avisos explicando o que foi omitido. Verifique os avisos em vez de assumir que os resultados da IA estão sempre presentes.
  • Cada etapa de IA concluída adiciona US$ 0,10 à chamada. Etapas de IA que falham ou expiram nunca são cobradas, e /enhance é cobrado apenas pelas etapas de IA que foram concluídas, sem taxa base por chamada.
  • Se cada etapa de IA solicitada falhar, a chamada será gratuita e a resposta conterá apenas avisos, sem dados. Sua análise armazenada permanece inalterada nesse caso, portanto, a cópia que você já possui ainda está atualizada. Os endpoints de criação sempre retornam dados, pois sua taxa base cobre o próprio relatório.

Parâmetros Obrigatórios

analysisIdstring

The _id of an analysis previously created with your API key

Exemplo: 000000000000000000000000

Parâmetros Opcionais

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.

Exemplo: true

addAIExpenseEstimatesboolean

Estimate operating expenses with AI instead of using category defaults

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

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 de IA é opcional por solicitação através de addAIComps e addAIExpenseEstimates, e cada etapa de IA tem tempo limitado e falha abertamente. Uma solicitação que pediu IA ainda retorna 201 com uma análise completa e totalmente recalculada; qualquer coisa que não pôde ser executada é relatada na matriz de avisos de nível superior em vez de gerar um erro.

Tempos limite e limites de taxa

  • O trabalho de IA tem um orçamento de 90 segundos medido a partir do início da solicitação, não do momento em que a etapa de IA começa, portanto, a geocodificação e a criação de análise contam para isso. Quando o orçamento se esgota, a análise é retornada sem a etapa de IA incompleta e um aviso de timeout.
  • 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 tentar novamente uma etapa de IA pulada, chame POST /v1/external/analysis/enhance com o mesmo analysisId em vez de criar a análise novamente. Enhance não tem custo de chamada base, portanto, uma nova tentativa custa apenas as etapas de IA que são concluídas.

Avisos na resposta

Uma resposta 201 ainda pode conter uma matriz de avisos. Trate-a como o registro do que não foi executado e verifique-a antes de assumir que os resultados da IA estão presentes. Cada etapa relatada aqui foi omitida, e etapas omitidas 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 dos anúncios para o endereço não estavam prontas a tempo: nenhuma foi encontrada, poucas foram utilizáveis ou a galeria ainda estava em processamento quando o orçamento se esgotou. As fotos são coletadas em segundo plano após a criação de uma análise, portanto, tentar novamente com /enhance logo depois geralmente é bem-sucedido.
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 do modelo não estava disponível. Isso é transitório, então 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 IA de comparáveis já está trabalhando nesta análise. Espere antes de tentar novamente: a execução mantém um bloqueio por 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 do modelo não estava disponível. Isso é transitório, então 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 etapa de IA concluída adiciona US$ 0,10 à chamada. Etapas que expiram, falham ou recorrem à projeção existente não são cobradas (aiComps.applied definido como falso significa que as comparações de IA não foram cobradas), e uma chamada /enhance onde cada etapa solicitada foi ignorada não é cobrada.

Limites de taxa

Os limites são contados por IP do chamador, a menos que uma linha diga o contrário. Respostas limitadas carregam X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma solicitação acima do limite retorna 429 com um cabeçalho Retry-After em segundos e nunca é cobrada, então espere esse tempo antes de tentar novamente.

100 por segundo
Cada rota /v1/external.
5 por minuto
POST /v1/external/analysis/enhance e execuções do Listing Optimizer (run_listing_optimization).
10 por minuto
Solicitações que definem addAIComps ou addAIExpenseEstimates, por chave de API, com no máximo 2 em andamento.
10 a 60 por minuto
Listagens ativas 10; detalhes do imóvel, estimativas de aluguel e conta 30; horas de participação material de registro 60.
2.000 por dia
Pesquisas de dados (estimativas de receita, tarifas noturnas, comparáveis, listagens e fotos, listagens ativas, detalhes do imóvel e estimativas de aluguel) por conta, compartilhadas pela API REST e pelo servidor MCP, e até 2.500 linhas de listagem por dia. O limite é redefinido às 00:00 UTC.

Códigos de erro

A API da BNBCalc usa códigos de status HTTP padrão para indicar o sucesso ou a falha das solicitações. Solicitações bem-sucedidas retornam códigos 2xx, enquanto erros retornam códigos 4xx ou 5xx com informações adicionais no corpo da resposta. Solicitações com falha (4xx ou 5xx) nunca são cobradas.

201
Criado: a análise foi criada ou aprimorada e está na resposta
400
Requisição inválida - Parâmetros inválidos
401
Não autorizado - Chave de API inválida
402
Payment Required - A conta da chave não tem uma assinatura de API ativa ou não tem mais créditos do Listing Optimizer
403
Forbidden - The analysis does not belong to your API key, or AI estimates are disabled
404
Not Found - A análise, o anúncio ou o local solicitado não foi encontrado
409
Conflict - Uma execução de IA ou do Listing Optimizer já está em andamento, a análise mudou desde a leitura ou o relatório ainda não está pronto
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 - Um modelo de IA ou a fonte de anúncios está temporariamente indisponível; tente novamente mais tarde
Verificar status da API

Guias da API

Preço da API

Veja o que a API BNBCalc custa: $0 por mês, $0.20 por relatório e $0.10 por etapa de IA concluída.

Casos de Uso da API

Veja como plataformas de PropTech, investidores, credores, operadores e analistas usam a API em fluxos de trabalho de produção.

Cobertura de Dados

Entenda a cobertura internacional de propriedades, estimativas baseadas em comparáveis, entradas de localização e onde a API se encaixa.

Comparação da API

Veja como a API BNBCalc se compara com a API AirDNA e outras APIs de dados do Airbnb em acesso, modelo de precificação e saída.

Planilhas Google

Analise uma lista de endereços no Planilhas Google com um Apps Script curto.

Servidor MCP

Conecte Claude, Cursor ou VS Code ao BNBCalc e execute estimativas de receita e análises de negócios do seu assistente de IA.

Guia de configuração MCP

Conecte Claude, ChatGPT, Claude Code, Cursor ou VS Code ao servidor MCP, passo a passo.

Referência MCP

Como o servidor MCP autentica, cada ferramenta com seu preço, aprovação de ferramentas pagas e limites.

Registro de alterações

O que mudou na API REST e no servidor MCP, do mais recente para o mais antigo.

Status

Verificações em tempo real da API REST e do servidor MCP.