Referência de API

pontos finais

POSTCriar Análise de Compra POSTCriar análise de arbitragem POSTCriar análise própria POSTCriar análise Cohost

RECURSOS

Primeiros Passos Autenticação Códigos de erro

Documentação da API

Bem-vindo à API BNBCalc. Esta documentação ajudará você a integrar as nossas ferramentas de análise imobiliária na sua aplicação.

Nossa API RESTful proporciona acesso programático aos dados abrangentes de aluguel de curto prazo do BNBCalc, estimativas de receita de propriedade, análise de mercado e projeções de investimento. Quer você esteja desenvolvendo software de gestão imobiliária, plataformas de imóveis ou ferramentas de análise de investimentos, nossa API fornece os dados de que você precisa.

Primeiros Passos

Para começar a usar a API BNBCalc, você precisará:

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 utilizam HTTPS e retornam respostas em JSON. Nossa API segue os princípios RESTful e utiliza códigos de resposta HTTP padrão para indicar sucesso ou falha.

Autenticação

Todas as solicitações de API exigem autenticação usando uma chave de API. As chaves de API estão vinculadas à sua conta BNBCalc e devem ser mantidas seguras. Inclua sua chave de API no cabeçalho da solicitação como mostrado abaixo:

x-bnbcalc-api-key: YOUR_API_KEY

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

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.

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

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 requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}

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

Resposta de exemplo

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 4,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
  }
}

POST/v1/external/create/arb

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

Exemplo de solicitação

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/create/arb \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/create/arb',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
})
  }
);
const data = await response.json();

import requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}

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

Resposta de exemplo

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],,
    "monthlyRentUSD": 2000,
    "yearOneRentUSD": 24000,
    "monthlyRevenueUSD": 13432.825977452352,
    "monthlyExpensesUSD": 2263.6108575197586,
    "yearOneRevenueUSD": 161193.91172942822,
    "yearOneOperatingIncomeUSD": 134030.58143919113,
    "yearOneCashFlowUSD": 110030.58143919116,
    "yearOneCashOnCashPercentage": 1317.415965507557,
    "totalCashInvestment": 8352,
  }
}

POST/v1/external/analysis/create/owned

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

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 requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}

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

Resposta de exemplo

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 5.1,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
  }
}

POST/v1/external/analysis/create/cohost

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

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 requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}

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

Resposta de exemplo

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],,
    "yearOneRevenueUSD": 161193.91172942825,
    "yearOneCohostReturnUSD": 116059.61644518835,
    "yearOneCohostCommissionUSD": 32238.78234588565,
  }
}

Códigos de erro

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

200

Sucesso

400

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

401

Não autorizado - Chave de API inválida

429

Muitas solicitações - Limite de taxa excedido

500

Erro interno do servidor