A comparative market analysis (CMA) estimates a property's value by comparing it against recently sold or currently listed properties that are similar in size, age, location, and type. Running a CMA only needs a handful of attributes per property (beds, baths, living area, lot size, last sale, and a valuation range), yet historically the only way to get them from the API was to pull a full property record and pay for every attribute, most of which a CMA never reads.

The comps dataset solves that. It is a lightweight projection of exactly the 24 attributes a CMA needs. comps is an add-on to a base dataset, basic or core, and a token with the Basic Property Data tier plus the Comparable Properties dataset bills roughly one third of the per-record rate of a token with Core Property Data (Tax Assessor) alone. This guide covers when to reach for comps, how to combine it with other datasets, how it's billed and accessed, the fields it returns, and how to use it to shape the comparable-property results returned by the Property Search endpoint.

The published API reference is canonical. See the BatchData developer portal for the full request and response schema. This guide is the how-to companion.

When to use comps vs. core or valuation

Pick the dataset that matches the job:

comps: Use when you are comparing properties: running a CMA, scoring a list of subject properties, or powering a comps grid. It returns the comparison-relevant attributes and nothing else, and paired with the basic base dataset it is the cheapest way to get sale, size, and valuation signals at scale.
core: Use when you need the full property record: tax history, mortgage and lien detail, the complete ownership chain, full building characteristics, and every other attribute. A core record carries roughly 11× more attributes than comps and is priced accordingly.
valuation: Use when you need the full valuation detail. Note that comps already includes the three headline valuation fields (estimatedValue, priceRangeMin, priceRangeMax), so for most CMA work you do not need to add valuation on top of comps.

A good rule of thumb: if you are comparing properties, start with basic plus comps, and only step up to core when you need an attribute that basic and comps don't carry.

Supported dataset combinations

comps is a projection designed to ride on top of a base dataset. The supported combinations are:

["basic", "comps"]: Recommended. The address and identity fields from basic plus the 24 comp-analysis attributes. This is the smallest combination and the one the MCP comparables tools request by default.
["core", "comps"]: The full core record plus the comp-analysis projection, for when a single request genuinely needs both the complete record and the comp fields.
["basic", "comps", "valuation"]: Adds the full valuation dataset on top, when you need valuation detail beyond the three headline value fields.

Important: basic and core are mutually exclusive: a single request cannot include both. Choose basic for the lightweight combination or core for the full record, but never both in the same datasets array.

Access and pricing

How you access comps depends on your account's billing model:

Pay-as-you-go (no property data subscription): every dataset, including comps, is available under PAYG pricing. comps is an add-on and is billed for each record returned. A token cannot carry comps alone: every token carries one base data tier, and the comps rate is added to the rate of that tier. A token with the Basic Property Data tier plus comps bills roughly one third of the per-record rate of a token with Core Property Data (Tax Assessor) alone. A token with Core Property Data (Tax Assessor) plus comps bills more than core alone. For the rates that apply to your account, contact sales@batchdata.com.
Property data subscription: datasets are only accessible if you have purchased them. To use comps on a subscription, add the Comparable Properties add-on to your plan. The API does not fall back to PAYG pricing for datasets your subscription doesn't include.
On a subscription without the comps add-on: a request for ["basic", "comps"] or ["core", "comps"] will not error and will not be billed at the PAYG comps rate. Instead, the response returns the intersection of comps with whichever base dataset your token is provisioned for (basic or core). The comps-only fields are simply omitted from the response.
MCP comparables tools follow the same rule. Because comparable_property_preview and comparable_property_page request comps by default, on a subscription without the comps add-on they return the reduced intersection field set rather than the full comps projection.

If you don't see the Comparable Properties option when provisioning an API token, your account is most likely on a property data subscription without the comps add-on.

Provision a dedicated token with a base dataset and comps

Billing is driven by how the API token used to make a request is configured. The per-record charge is the sum of the rates of the datasets enabled on that token. The options.datasets array in a request selects which fields come back, and it does not change the price. A token with many datasets enabled can therefore bill at a higher rate than comparable analysis actually needs.

Because of this, the recommended practice for comp pulls is to provision a dedicated API token with the Basic Property Data tier and the Comparable Properties dataset, and nothing else. Every token you create on the API Tokens page carries one data tier, Basic Property Data or Core Property Data (Tax Assessor). Basic Property Data is the lower-cost tier, so this pair is the lowest-cost token for comparable analysis. A token provisioned for both core and comps bills more per record than core alone, because the rates of the two datasets are added together. This dedicated token holds a base data tier, Basic Property Data or Core Property Data (Tax Assessor), plus comps, because a token cannot carry comps alone. It also isolates this workflow from the broader tokens you use for fuller, more expensive record pulls.

When you create or edit the token on the API Tokens page, select the Basic Property Data tier, enable the Comparable Properties dataset, and leave everything else off. When you enable an endpoint on a token, the page selects every add-on by default, so clear the add-ons that this workflow does not need.

The 24 comps fields

The comps dataset returns the following 24 comp-analysis fields, grouped by category. The published spec on the developer portal is the canonical schema reference, and the internal data-dictionary sheet is the canonical source for the full field list; the table below is a quick reference.

#	Field	Type	Group
1	`building.bedroomCount`	integer	Building
2	`building.bathroomCount`	integer	Building
3	`building.livingAreaSquareFeet`	integer	Building
4	`building.totalBuildingAreaSquareFeet`	integer	Building
5	`building.yearBuilt`	integer	Building
6	`building.storyCount`	number	Building
7	`building.pool`	string	Building
8	`lot.lotSizeAcres`	number	Lot
9	`lot.lotSizeSquareFeet`	integer	Lot
10	`legal.subdivisionName`	string	Legal
11	`general.propertyTypeCategory`	string	Classification
12	`general.propertyTypeDetail`	string	Classification
13	`general.standardizedLandUseCode`	string	Classification
14	`general.vacant`	boolean	Classification
15	`owner.ownerStatusType`	string	Owner
16	`owner.ownerOccupied`	boolean	Owner
17	`sale.lastSale.price`	integer	Sale
18	`sale.lastSale.pricePerSquareFoot`	integer	Sale
19	`sale.lastSale.saleDate`	string (date)	Sale
20	`sale.flipLength`	integer	Sale
21	`listing.statusCategory`	string	Listing
22	`valuation.estimatedValue`	integer	Valuation
23	`valuation.priceRangeMin`	integer	Valuation
24	`valuation.priceRangeMax`	integer	Valuation

These fields map directly to the inputs a CMA relies on: building characteristics and lot size for like-for-like matching, classification and owner-occupancy for filtering, last-sale price and price-per-square-foot for the comparison itself, and the valuation range as a sanity check.

Note: alongside these 24 content fields, each record also returns the property _id identifier, so you will see 25 fields on the wire.

Running a comparable analysis with Property Search

The intended use of comps is to shape the comparable-property results returned by the Property Search endpoint (POST /api/v1/property/search). You supply a subject property via a compAddress object inside searchCriteria, and the API returns the properties most comparable to it, each one projected down to the 24 comps fields.

compAddress is a structured object (street / city / state / zip), not a free-text query string. The surrounding query scopes the geographic area the comparables are drawn from.

At its simplest, supply the subject property and request ["basic", "comps"]. The API applies sensible default matching rules:

{
  "searchCriteria": {
    "query": "San Antonio, TX",
    "compAddress": {
      "street": "10406 Burr Oak Dr",
      "city": "San Antonio",
      "state": "TX",
      "zip": "78230"
    }
  },
  "options": {
    "take": 10,
    "datasets": ["basic", "comps"]
  }
}

Tuning the comparable match

Each comparison dimension is controlled by a boolean use… toggle. When a toggle is on, a min/max pair bounds how far a comparable may differ from the subject property. For bedrooms, bathrooms, stories, and year built the bounds are deltas relative to the subject; for living area and lot size they are percentage deltas.

Option(s)	Default	What it controls
`useDistance`, `distanceMiles`	on, 1 mile	Restrict comparables to within a radius of the subject. Use the numeric `distanceMiles` (string distance values are deprecated).
`useBedrooms`, `minBedrooms`, `maxBedrooms`	on, −1 to +1	Match bedroom count within a delta of the subject (e.g. one fewer to one more).
`useYearBuilt`, `minYearBuilt`, `maxYearBuilt`	on, −10 to +10	Match year built within a span of years around the subject.
`useArea`, `minAreaPercent`, `maxAreaPercent`	off, −20% to +20%	Match living area within a percentage of the subject's square footage.
`useBathrooms`, `minBathrooms`, `maxBathrooms`	off, −1 to +1	Match bathroom count within a delta of the subject.
`useStories`, `minStories`, `maxStories`	off, −1 to +1	Match story count within a delta of the subject.
`useLotSize`, `minLotSizePercent`, `maxLotSizePercent`	off	Match lot size within a percentage of the subject's lot.
`useSubdivision`	off	Restrict comparables to the subject's subdivision / neighborhood.

A more selective request turns on additional dimensions and tightens the bounds:

{
  "searchCriteria": {
    "query": "San Antonio, TX",
    "compAddress": {
      "street": "10406 Burr Oak Dr",
      "city": "San Antonio",
      "state": "TX",
      "zip": "78230"
    }
  },
  "options": {
    "useDistance": true,
    "distanceMiles": 1,
    "useBedrooms": true,
    "minBedrooms": -1,
    "maxBedrooms": 1,
    "useYearBuilt": true,
    "minYearBuilt": -10,
    "maxYearBuilt": 10,
    "useArea": true,
    "minAreaPercent": -20,
    "maxAreaPercent": 20,
    "take": 25,
    "datasets": ["basic", "comps"]
  }
}

Aggregate metrics alongside the results

To get summary statistics across the matched comparables, add "aggComparablesMetrics": true to the same request. The response then includes an aggComparablesMetrics object (under results.meta.results) with averagePrice, averagePricePerSqft, and estimatedValue, computed across the comparables you matched, returned alongside the per-property rows you requested with take.

Using comps through the BatchData MCP server

The preview and page tools of the BatchData MCP server request the basic and comps datasets by default, so any MCP client (Claude Desktop, an IDE assistant, or your own integration) gets the slim comp record. The typical workflow is count → preview → page:

comparable_property_count: Returns the number of matching comparables plus the aggregate metrics (average price, average price per square foot, estimated value), so you can size the result set before pulling rows.
comparable_property_preview: Returns a focused 16-field preview projection of the top comparables, backed by the ["basic", "comps"] combination, ideal for a quick scan before committing to a full pull.
comparable_property_page: Pages through the full comparable set. It requests the basic + comps combination by default.

The lower comps cost is not automatic, because the price follows the token and not the datasets that the tools request. An MCP OAuth sign-in grants core and comps by default, which on pay-as-you-go bills more per record than core alone. To lower the cost of MCP comp pulls, an account owner or admin opens API Tokens, selects the MCP Server Datasets tab, chooses the Basic Property Data tier, checks Comparable Properties, and selects Save Configuration. Saving ends the MCP sessions that are connected for the account, so users reconnect after the change.

A note on Property Lookup

comps is a valid dataset on the Property Lookup endpoint (POST /api/v1/property/lookup) as well, but Lookup retrieves records for addresses you already know. It does not calculate comparables. The comparable-matching options above apply only to Property Search. comps was designed to shape the comparable-property results of a Property Search, so that is where it delivers its value; reach for Property Lookup only when you already have the specific addresses you want and simply want their records.

Migrating from core

If you are currently requesting core purely to run comparable analysis, switch to basic plus comps:

Provision a token with the Basic Property Data tier and the Comparable Properties dataset (see Provision a dedicated token with a base dataset and comps above), then replace "datasets": ["core"] with "datasets": ["basic", "comps"] in your comparable searches. The token change lowers the price. The request change only selects which fields come back.
Update any field references. The comp-analysis fields keep the same paths (e.g. sale.lastSale.price, valuation.estimatedValue), so most mappings carry over unchanged. If your code reads attributes outside the 24-field projection, keep core (or request ["core", "comps"] together).
Confirm your billing expectations: on the lowest-cost token for comparable analysis (the Basic Property Data tier plus the Comparable Properties dataset), comp pulls cost roughly one third of the equivalent core pulls.

For the complete request and response schema, see the BatchData developer portal.

Comps dataset developer guide: low-cost comparable-property analysis