API Reference

ENDPOINTS

POSTCreate Buy Analysis POSTCreate Arbitrage Analysis POSTCreate Owned Analysis POSTCreate Cohost Analysis

RESOURCES

Getting Started Authentication Error Codes

API Documentation

Welcome to the BNB Calc API. This documentation will help you integrate our property analysis tools into your application.

Get property data for your apps, reports, or analysis with our easy REST API—perfect for real estate, underwriting, or management tools.

Getting Started

To start using the BNB Calc API, you'll need to:

1. Create a BNB Calc account or sign in to your existing account

2. Navigate to your account settings to generate an API key

3. Include your API key in all API requests using the x-bnbcalc-api-key header

4. Start making requests to access property data and analysis

All API endpoints use HTTPS and return JSON responses. Our API follows RESTful principles and uses standard HTTP response codes to indicate success or failure.

Authentication

All API requests require authentication using an API key. API keys are tied to your BNB Calc account and should be kept secure. Include your API key in the request header as shown below:

x-bnbcalc-api-key: YOUR_API_KEY

You can generate API keys from your account settings page. Include the x-bnbcalc-api-key header in every API request to authenticate.

POST/v1/external/analysis/create/buy

Create Buy Analysis

Create a new buy analysis for a property. Requires property details, location information, and purchase price.

Location Parameters (Conditional)

⚠️ Either provide both lat AND lng, OR provide fullAddress. At least one method is required.

latnumberconditional

Latitude coordinate (must be provided with lng if fullAddress is not used)(e.g., 27.7676)

lngnumberconditional

Longitude coordinate (must be provided with lat if fullAddress is not used)(e.g., -82.6403)

fullAddressstringconditional

Complete property address (can be used instead of lat/lng coordinates)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Required Parameters

purchasePriceUSDnumberrequired

Purchase price in USD(e.g., 350000)

bedroomsnumberrequired

Number of bedrooms(e.g., 3)

bathroomsnumberrequired

Number of bathrooms(e.g., 2)

accomodatesnumberrequired

Number of guests the property can accommodate(e.g., 6)

Optional Parameters

monthlyRentUSDnumberoptional

Expected monthly rent in USD for long-term rental(e.g., 2500)

interestRatePercentagenumberoptional

Interest rate percentage (0-15)(e.g., 5.1)

squareFeetnumberoptional

Property square footage(e.g., 1500)

statestringoptional

State name(e.g., Florida)

citystringoptional

City name(e.g., St. Petersburg)

countystringoptional

County name(e.g., Pinellas County)

postalCodestringoptional

Postal/ZIP code(e.g., 33703)

countrystringoptional

Country name(e.g., United States)

streetstringoptional

Street name(e.g., 2nd Avenue North)

streetNumberstringoptional

Street number(e.g., 4935)

unitstringoptional

Unit/apartment number if applicable

Example Request

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

Example Response

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

Create Arbitrage Analysis

Create a new arbitrage (rental arbitrage) analysis for a property. Uses the same required fields as buy analysis.

Location Parameters (Conditional)

⚠️ Either provide both lat AND lng, OR provide fullAddress. At least one method is required.

latnumberconditional

Latitude coordinate (must be provided with lng if fullAddress is not used)(e.g., 27.7676)

lngnumberconditional

Longitude coordinate (must be provided with lat if fullAddress is not used)(e.g., -82.6403)

fullAddressstringconditional

Complete property address (can be used instead of lat/lng coordinates)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Required Parameters

monthlyRentUSDnumberrequired

Expected monthly rent in USD for long-term rental(e.g., 2500)

bedroomsnumberrequired

Number of bedrooms(e.g., 3)

bathroomsnumberrequired

Number of bathrooms(e.g., 2)

accomodatesnumberrequired

Number of guests the property can accommodate(e.g., 6)

Optional Parameters

purchasePriceUSDnumberoptional

Purchase price in USD(e.g., 350000)

squareFeetnumberoptional

Property square footage(e.g., 1500)

statestringoptional

State name(e.g., Florida)

citystringoptional

City name(e.g., St. Petersburg)

countystringoptional

County name(e.g., Pinellas County)

postalCodestringoptional

Postal/ZIP code(e.g., 33703)

countrystringoptional

Country name(e.g., United States)

streetstringoptional

Street name(e.g., 2nd Avenue North)

streetNumberstringoptional

Street number(e.g., 4935)

unitstringoptional

Unit/apartment number if applicable

Example Request

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

Example Response

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

Create Owned Analysis

Create a new owned property analysis. Uses the same required fields as buy analysis.

Location Parameters (Conditional)

⚠️ Either provide both lat AND lng, OR provide fullAddress. At least one method is required.

latnumberconditional

Latitude coordinate (must be provided with lng if fullAddress is not used)(e.g., 27.7676)

lngnumberconditional

Longitude coordinate (must be provided with lat if fullAddress is not used)(e.g., -82.6403)

fullAddressstringconditional

Complete property address (can be used instead of lat/lng coordinates)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Required Parameters

purchasePriceUSDnumberrequired

Purchase price in USD(e.g., 350000)

downPaymentPercentagenumberrequired

Down payment percentage (0-40)(e.g., 20)

interestRatePercentagenumberrequired

Interest rate percentage (0-15)(e.g., 5.1)

mortgageLengthnumberrequired

Mortgage length in years (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberrequired

Years remaining on mortgage (Can't be higher than mortgage length)

bedroomsnumberrequired

Number of bedrooms(e.g., 3)

bathroomsnumberrequired

Number of bathrooms(e.g., 2)

accomodatesnumberrequired

Number of guests the property can accommodate(e.g., 6)

Optional Parameters

monthlyRentUSDnumberoptional

Expected monthly rent in USD for long-term rental(e.g., 2500)

squareFeetnumberoptional

Property square footage(e.g., 1500)

statestringoptional

State name(e.g., Florida)

citystringoptional

City name(e.g., St. Petersburg)

countystringoptional

County name(e.g., Pinellas County)

postalCodestringoptional

Postal/ZIP code(e.g., 33703)

countrystringoptional

Country name(e.g., United States)

streetstringoptional

Street name(e.g., 2nd Avenue North)

streetNumberstringoptional

Street number(e.g., 4935)

unitstringoptional

Unit/apartment number if applicable

Example Request

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

Example Response

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

Create Cohost Analysis

Create cohost history

Location Parameters (Conditional)

⚠️ Either provide both lat AND lng, OR provide fullAddress. At least one method is required.

latnumberconditional

Latitude coordinate (must be provided with lng if fullAddress is not used)(e.g., 27.7676)

lngnumberconditional

Longitude coordinate (must be provided with lat if fullAddress is not used)(e.g., -82.6403)

fullAddressstringconditional

Complete property address (can be used instead of lat/lng coordinates)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Required Parameters

bedroomsnumberrequired

Number of bedrooms(e.g., 3)

bathroomsnumberrequired

Number of bathrooms(e.g., 2)

accomodatesnumberrequired

Number of guests the property can accommodate(e.g., 6)

Optional Parameters

cohostCommissionPercentagenumberoptional

Cohost commission percentage(e.g., 10)

squareFeetnumberoptional

Property square footage(e.g., 1500)

statestringoptional

State name(e.g., Florida)

citystringoptional

City name(e.g., St. Petersburg)

countystringoptional

County name(e.g., Pinellas County)

postalCodestringoptional

Postal/ZIP code(e.g., 33703)

countrystringoptional

Country name(e.g., United States)

streetstringoptional

Street name(e.g., 2nd Avenue North)

streetNumberstringoptional

Street number(e.g., 4935)

unitstringoptional

Unit/apartment number if applicable

Example Request

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

Example Response

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

Error Codes

The BNB Calc API uses standard HTTP response status codes to indicate the success or failure of API requests. Successful requests return 2xx codes, while errors return 4xx or 5xx codes with additional error information in the response body. You will only be charged for successful requests.

200

Success

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid API key

429

Too Many Requests - Rate limit exceeded

500

Internal Server Error