> For AI agents: BNBCalc's MCP server is at https://atlas.bnbcalc.com/mcp (setup: https://www.bnbcalc.com/developers/mcp). Index of every BNBCalc page: https://www.bnbcalc.com/llms.txt

# Airbnb Data API Documentation

Use the BNBCalc Airbnb Data API to get property revenue, occupancy, ADR, active Airbnb comparable listings, percentiles, investment metrics, and hosted report URLs for apps, reports, underwriting, and management tools.

- Base URL: `https://atlas.bnbcalc.com`
- API key header: `x-bnbcalc-api-key`
- MCP server: `https://atlas.bnbcalc.com/mcp`
- API Pricing: See what the BNBCalc API costs: $0 a month, $0.20 per report and $0.10 per AI step that completes. https://www.bnbcalc.com/developers/rest-api/pricing
- Updated: 2026-11-12
- OpenAPI: https://www.bnbcalc.com/developers/openapi.json
- HTML: https://www.bnbcalc.com/developers/rest-api/docs

---

## Getting Started

1. Create a BNBCalc account and generate an API key in your dashboard settings.
2. Send your key in the x-bnbcalc-api-key header on every request.
3. POST a property's location and details to any analysis endpoint and read the JSON response, including the hosted report URL.

All API endpoints use HTTPS and return JSON responses. Keep API keys on your server, not in browser or mobile client code. External API routes are currently throttled at 100 requests per second and use 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 BNBCalc account, should be kept server-side, and should never be exposed in frontend code. Include your API key in the request header as shown below:

```
x-bnbcalc-api-key: YOUR_API_KEY
```

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

---

## Create analyses

> 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 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.
>
> Each AI step 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 steps that completed, with no base call fee.

### Create Buy Analysis

`POST /v1/external/analysis/create/buy`

Create a buy analysis for a short-term rental acquisition. Send location, property details, and purchase price to return projected revenue, occupancy, comps, cash flow, and ROI metrics.

MCP tool: `create_buy_analysis`

#### Location Parameters (Conditional)

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

- `lat` (number): Latitude coordinate (must be provided with lng if fullAddress is not used). Example: `27.7676`
- `lng` (number): Longitude coordinate (must be provided with lat if fullAddress is not used). Example: `-82.6403`
- `fullAddress` (string): Complete property address (can be used instead of lat/lng coordinates). Example: `4935 2nd Avenue North, St. Petersburg, FL 33703`

#### Required Parameters

- `purchasePriceUSD` (number): Purchase price in USD. Example: `350000`
- `bedrooms` (number): Number of bedrooms. Example: `3`
- `bathrooms` (number): Number of bathrooms. Example: `2`
- `accomodates` (number): Number of guests the property can accommodate. Example: `6`

#### Optional Parameters

- `monthlyRentUSD` (number): Expected monthly rent in USD for long-term rental. Example: `2500`
- `interestRatePercentage` (number): Interest rate percentage (0-15). Example: `5.1`
- `downPaymentPercentage` (number): Down payment percentage (0-40). Example: `25`
- `mortgageLength` (number): Mortgage length in years (0-30). Example: `15`
- `squareFeet` (number): Property square footage. Example: `1500`
- `state` (string): State name. Example: `Florida`
- `city` (string): City name. Example: `St. Petersburg`
- `county` (string): County name. Example: `Pinellas County`
- `postalCode` (string): Postal/ZIP code. Example: `33703`
- `country` (string): Country name. Example: `United States`
- `street` (string): Street name. Example: `2nd Avenue North`
- `streetNumber` (string): Street number. Example: `4935`
- `unit` (string): Unit/apartment number if applicable
- `addAIComps` (boolean): Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address. Example: `true`
- `addAIExpenseEstimates` (boolean): Estimate operating expenses with AI instead of using category defaults. Example: `true`

#### Example Request

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

```javascript
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();
```

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

#### Example Response

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

### Create Arbitrage Analysis

`POST /v1/external/analysis/create/arb`

Create a rental arbitrage analysis for a leased property. Send monthly rent, location, and property details to return projected Airbnb revenue, cash flow, and comparable listings.

MCP tool: `create_arbitrage_analysis`

#### Location Parameters (Conditional)

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

- `lat` (number): Latitude coordinate (must be provided with lng if fullAddress is not used). Example: `27.7676`
- `lng` (number): Longitude coordinate (must be provided with lat if fullAddress is not used). Example: `-82.6403`
- `fullAddress` (string): Complete property address (can be used instead of lat/lng coordinates). Example: `4935 2nd Avenue North, St. Petersburg, FL 33703`

#### Required Parameters

- `monthlyRentUSD` (number): Expected monthly rent in USD for long-term rental. Example: `2500`
- `bedrooms` (number): Number of bedrooms. Example: `3`
- `bathrooms` (number): Number of bathrooms. Example: `2`
- `accomodates` (number): Number of guests the property can accommodate. Example: `6`

#### Optional Parameters

- `purchasePriceUSD` (number): Purchase price in USD. Example: `350000`
- `squareFeet` (number): Property square footage. Example: `1500`
- `state` (string): State name. Example: `Florida`
- `city` (string): City name. Example: `St. Petersburg`
- `county` (string): County name. Example: `Pinellas County`
- `postalCode` (string): Postal/ZIP code. Example: `33703`
- `country` (string): Country name. Example: `United States`
- `street` (string): Street name. Example: `2nd Avenue North`
- `streetNumber` (string): Street number. Example: `4935`
- `unit` (string): Unit/apartment number if applicable
- `addAIComps` (boolean): Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address. Example: `true`
- `addAIExpenseEstimates` (boolean): Estimate operating expenses with AI instead of using category defaults. Example: `true`

#### Example Request

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

```javascript
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();
```

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

#### Example Response

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

### Create Owned Analysis

`POST /v1/external/analysis/create/owned`

Create an owned-property analysis for a property already in your portfolio. Include mortgage terms to return STR revenue, cash flow, principal paydown, appreciation, and ROI metrics.

MCP tool: `create_owned_analysis`

#### Location Parameters (Conditional)

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

- `lat` (number): Latitude coordinate (must be provided with lng if fullAddress is not used). Example: `27.7676`
- `lng` (number): Longitude coordinate (must be provided with lat if fullAddress is not used). Example: `-82.6403`
- `fullAddress` (string): Complete property address (can be used instead of lat/lng coordinates). Example: `4935 2nd Avenue North, St. Petersburg, FL 33703`

#### Required Parameters

- `purchasePriceUSD` (number): Purchase price in USD. Example: `350000`
- `downPaymentPercentage` (number): Down payment percentage (0-40). Example: `20`
- `interestRatePercentage` (number): Interest rate percentage (0-15). Example: `5.1`
- `mortgageLength` (number): Mortgage length in years (0-30). Example: `30`
- `yearsRemainingOnMortgage` (number): Years remaining on mortgage (Can't be higher than mortgage length)
- `bedrooms` (number): Number of bedrooms. Example: `3`
- `bathrooms` (number): Number of bathrooms. Example: `2`
- `accomodates` (number): Number of guests the property can accommodate. Example: `6`

#### Optional Parameters

- `monthlyRentUSD` (number): Expected monthly rent in USD for long-term rental. Example: `2500`
- `squareFeet` (number): Property square footage. Example: `1500`
- `state` (string): State name. Example: `Florida`
- `city` (string): City name. Example: `St. Petersburg`
- `county` (string): County name. Example: `Pinellas County`
- `postalCode` (string): Postal/ZIP code. Example: `33703`
- `country` (string): Country name. Example: `United States`
- `street` (string): Street name. Example: `2nd Avenue North`
- `streetNumber` (string): Street number. Example: `4935`
- `unit` (string): Unit/apartment number if applicable
- `addAIComps` (boolean): Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address. Example: `true`
- `addAIExpenseEstimates` (boolean): Estimate operating expenses with AI instead of using category defaults. Example: `true`

#### Example Request

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

```javascript
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();
```

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

#### Example Response

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

### Create Cohost Analysis

`POST /v1/external/analysis/create/cohost`

Create a co-hosting analysis for an owner lead or operator workflow. Return projected STR revenue, co-host commission, host return, and comparable listings.

MCP tool: `create_cohost_analysis`

#### Location Parameters (Conditional)

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

- `lat` (number): Latitude coordinate (must be provided with lng if fullAddress is not used). Example: `27.7676`
- `lng` (number): Longitude coordinate (must be provided with lat if fullAddress is not used). Example: `-82.6403`
- `fullAddress` (string): Complete property address (can be used instead of lat/lng coordinates). Example: `4935 2nd Avenue North, St. Petersburg, FL 33703`

#### Required Parameters

- `bedrooms` (number): Number of bedrooms. Example: `3`
- `bathrooms` (number): Number of bathrooms. Example: `2`
- `accomodates` (number): Number of guests the property can accommodate. Example: `6`

#### Optional Parameters

- `cohostCommissionPercentage` (number): Cohost commission percentage. Example: `10`
- `squareFeet` (number): Property square footage. Example: `1500`
- `state` (string): State name. Example: `Florida`
- `city` (string): City name. Example: `St. Petersburg`
- `county` (string): County name. Example: `Pinellas County`
- `postalCode` (string): Postal/ZIP code. Example: `33703`
- `country` (string): Country name. Example: `United States`
- `street` (string): Street name. Example: `2nd Avenue North`
- `streetNumber` (string): Street number. Example: `4935`
- `unit` (string): Unit/apartment number if applicable
- `addAIComps` (boolean): Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address. Example: `true`
- `addAIExpenseEstimates` (boolean): Estimate operating expenses with AI instead of using category defaults. Example: `true`

#### Example Request

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

```javascript
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();
```

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

#### Example Response

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

---

## AI enrichment

### Enhance Analysis with AI

`POST /v1/external/analysis/enhance`

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.

MCP tool: `enhance_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.
>
> When an AI step cannot complete, the response still returns 201 with the valid analysis and a warnings array explaining what was skipped. Check warnings rather than assuming AI results are always present.
>
> Each AI step 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 steps that completed, with no base call fee.
>
> If every AI step you requested fails, the call is free and the response contains only warnings, with no data. Your stored analysis is unchanged in that case, so the copy you already have is still current. Create endpoints always return data, because their base fee covers the report itself.

#### Required Parameters

- `analysisId` (string): The _id of an analysis previously created with your API key. Example: `000000000000000000000000`

#### Optional Parameters

- `addAIComps` (boolean): Select comparables with AI and apply the resulting revenue benchmark. US properties only, and requires at least 8 usable listing photos for the address. Example: `true`
- `addAIExpenseEstimates` (boolean): Estimate operating expenses with AI instead of using category defaults. Example: `true`

#### Example Request

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

```javascript
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();
```

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

#### Example Response

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

---

## Connect AI assistants with MCP

The BNBCalc MCP server gives Claude, ChatGPT, Cursor, VS Code and other MCP clients the same analyses and data as this API. Clients sign in with your BNBCalc account or send your API key; MCP and REST calls share one API subscription and its usage.

- MCP server: `https://atlas.bnbcalc.com/mcp`
- MCP reference: https://www.bnbcalc.com/developers/mcp/docs
- MCP setup guide: https://www.bnbcalc.com/developers/mcp/setup
- Markdown: https://www.bnbcalc.com/developers/mcp.md

---

## AI enrichment behavior

AI enrichment is opt-in per request through addAIComps and addAIExpenseEstimates, and every AI step is time-bounded and fails open. A request that asked for AI still returns 201 with a complete, fully recalculated analysis; anything that could not run is reported in the top-level warnings array instead of raising an error.

### Timeouts and rate limits

- AI work has a 90-second budget measured from the start of the request, not from the moment the AI step begins, so geocoding and analysis creation count against it. When the budget runs out, the analysis is returned without the unfinished AI step and a timeout warning.
- Set your client timeout to at least 300 seconds. Most AI calls return well inside the budget, but a client that aborts earlier than the server's own deadline turns a billable, completed analysis into a lost response.
- A model call needs at least 45 seconds of remaining budget to start. A request that spends most of its budget waiting for listing photos returns ai_comps_timed_out without calling the model rather than starting a run it cannot finish.
- Requests that set an AI flag are rate limited per API key: 10 per minute, with at most 2 in flight at once. Exceeding either returns 429 with a Retry-After header, and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are set on every AI request. Calls without an AI flag are not affected by this limit.
- To retry a skipped AI step, call POST /v1/external/analysis/enhance with the same analysisId rather than creating the analysis again. Enhance carries no base call fee, so a retry costs only the AI steps that complete.

### Response warnings

A 201 response can still carry a warnings array. Treat it as the record of what did not run and check it before assuming AI results are present. Every step reported here was skipped, and skipped steps are never billed.

| Warning | Meaning |
| ------- | ------- |
| `ai_comps_requires_user_scoped_api_key` | AI comps require an API key bound to a user account. The key could not be resolved to an owner, so the comp selector never ran. |
| `ai_comps_unavailable_for_property` | AI comps are available for United States properties only, and the stored analysis is outside that scope. |
| `ai_comps_photos_not_ready` | Usable listing photos for the address were not ready in time: none were found, too few were usable, or the gallery was still processing when the budget ran out. Photos are gathered in the background after an analysis is created, so retrying with /enhance shortly afterwards usually succeeds. |
| `ai_comps_timed_out` | The AI budget ran out before the model returned, so the deterministic comparables and revenue projection were kept. |
| `ai_comps_benchmark_fallback` | The model ran but selected too few comparables to form a benchmark, so the existing revenue projection was kept. Nothing was written to the analysis and the step was not charged. |
| `ai_comps_model_unavailable` | The model provider was unavailable. This is transient, so retry with /enhance. |
| `ai_comps_already_applied` | This analysis already has a valid AI benchmark, so nothing was re-run and nothing was charged. Editing the property invalidates it, and the next call runs for real. |
| `ai_comps_run_in_progress` | Another AI comps run is already working on this analysis. Wait before retrying: the run holds a lock for up to 10 minutes. |
| `ai_comps_analysis_changed` | The analysis was edited while the model was running, so the benchmark was not written rather than overwriting the newer values. Retry with /enhance. |
| `ai_comps_forbidden` | The analysis was not created with this API key, so AI comps could not run against it. |
| `ai_comps_failed` | AI comps could not be completed for another reason. The analysis itself is valid and unchanged. |
| `ai_expense_estimates_timed_out` | The AI budget ran out before the expense estimator returned, so the default operating expenses were kept. |
| `ai_expense_estimates_no_proposals` | The estimator produced no expense proposals for this property, so no operating expense was changed. |
| `ai_expense_estimates_stale_preview` | The analysis changed while the estimate was being prepared, so it was discarded rather than applied to stale inputs. Retry with /enhance. |
| `ai_expense_estimates_model_unavailable` | The model provider was unavailable. This is transient, so retry with /enhance. |
| `ai_expense_estimates_already_applied` | This analysis already has AI-estimated expenses, so nothing was re-run and nothing was charged. |
| `ai_expense_estimates_unavailable_for_property` | No operating expense field on this analysis was eligible for AI estimation, so its default expenses were kept. |
| `ai_expense_estimates_forbidden` | The analysis was not created with this API key, so AI expense estimates could not run against it. |
| `ai_expense_estimates_failed` | AI expense estimates could not be applied. The analysis keeps its default operating expenses. |

Match on the ai_comps_ and ai_expense_estimates_ prefixes rather than the exact string: any other code with those prefixes means that step failed, was not applied, and was not charged.

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

### aiComps.warnings

The nested aiComps.warnings array is a different signal from the top-level one: it describes the quality of the comparable pool the model worked with, not a step that failed. Read aiComps.applied to know whether the AI benchmark was actually written to the analysis.

| Warning | Meaning |
| ------- | ------- |
| `thin_benchmark_pool` | Fewer than four comparables backed the benchmark, so it rests on a small sample. |
| `no_benchmark_comps` | No comparable passed selection. The benchmark is empty and the revenue projection was left unchanged. |
| `ai_benchmark_fallback_to_projected_revenue` | Fewer than three comparables were selected, so the existing revenue projection was kept instead of the AI benchmark. This is the same outcome reported as ai_comps_benchmark_fallback at the top level. |
| `minimum_benchmark_pool_backfill` | The benchmark pool was padded with comparables the model did not choose in order to reach the minimum count. |

### Billing when AI is partial

Each AI step that completes adds $0.10 to the call. Steps that time out, fail, or fall back to the existing projection are not charged (aiComps.applied set to false means AI comps were not billed), and an /enhance call where every requested step was skipped is not billed at all.

---

## Rate limits

Limits count per caller IP unless a row says otherwise. Throttled responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A request over a limit returns 429 with a Retry-After header in seconds and is never billed, so wait that long before you retry.

| Limit | Applies to |
| ----- | ---------- |
| 100 per second | Every /v1/external route. |
| 5 per minute | POST /v1/external/analysis/enhance and Listing Optimizer runs (run_listing_optimization). |
| 10 per minute | Requests that set addAIComps or addAIExpenseEstimates, per API key, with at most 2 in flight. |
| 10 to 60 per minute | Live listings 10; property details, rent estimates and account 30; logging material participation hours 60. |
| 2,000 per day | Data lookups (revenue estimates, nightly rates, comparables, listings and photos, live listings, property details and rent estimates) per account, shared by the REST API and the MCP server, and up to 2,500 listing rows a day. The cap resets at 00:00 UTC. |

---

## Error Codes

The BNBCalc 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. Failed requests (4xx or 5xx) are never charged.

| Code | Description |
| ---- | ----------- |
| `201` | Created: the analysis was created or enhanced and is in the response |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid API key |
| `402` | Payment Required - The key's account has no active API subscription, or no Listing Optimizer credits are left |
| `403` | Forbidden - The analysis does not belong to your API key, or AI estimates are disabled |
| `404` | Not Found - The requested analysis, listing or location was not found |
| `409` | Conflict - An AI or Listing Optimizer run is already in progress, the analysis changed since you read it, or the report is not ready yet |
| `429` | Too Many Requests - External API route limit exceeded |
| `500` | Internal Server Error |
| `502` | Bad Gateway - The AI model returned an unusable response |
| `503` | Service Unavailable - An AI model or listing source is temporarily unavailable; try again later |
