Skip to main content
The /api/v1/benchmarks endpoint exposes a statistical summary of key pricing and financing metrics aggregated across the Home Service Data catalog. For every supported metric you receive a full distribution: average, median, 25th and 75th percentiles, minimum, maximum, standard deviation, and sample size. Responses can be narrowed with metric-specific filters such as manufacturer, payment_type, term_months, or financier, letting your quoting tool or CRM surface hyper-relevant market context rather than broad averages. Access to each metric is governed by the dataset scope associated with your API key.

​
Endpoint

GET https://homeservicedata.com/api/v1/benchmarks

​
Authentication

All requests must include a valid API key in the x-api-key header. Each metric maps to a specific dataset scope; your key must have the corresponding dataset enabled.
​
x-api-key
string
required
Your secret API key. Generate or rotate keys from the dashboard under Settings → API Keys.
Dataset access is enforced per metric. Requesting a metric your key is not provisioned for returns a 403 Forbidden response. Contact your account manager to enable additional datasets.

​
Query Parameters

​
metric
string
required
The metric key to compute benchmarks for. Must be one of the registered keys listed in the table below. An error is returned if this parameter is missing or if the key is not recognized.
KeyLabelUnitDataset Scope
dealer_feeDealer feepercentfinancing
inverter_base_costInverter costcurrencyhardware
inverter_price_per_wattInverter $/watt addcurrencyhardware
interest_rateRatepercentfinancing

​
Metric-Specific Filter Parameters

The following optional filters are accepted depending on which metric you request. Unrecognized filter keys for a given metric are silently ignored.

​
dealer_fee filters

​
payment_type
string
Restrict results to a single payment type. Accepted values: loan, lease, ppa, cash.
​
term_months
number
Restrict results to a specific loan term, expressed as an integer number of months (e.g. 120, 180, 240).
​
financier
string
Restrict results to a specific lender by its internal key, e.g. "goodleap" or "sunlight".

​
inverter_base_cost filters

​
manufacturer
string
Restrict benchmark to a single inverter brand, e.g. "Enphase" or "SolarEdge".
​
is_archived
boolean
When true, includes archived (discontinued) inverter products in the calculation. Defaults to excluding archived records if omitted.

​
inverter_price_per_watt filters

​
manufacturer
string
Restrict the per-watt benchmark to inverters from a specific manufacturer.

​
interest_rate filters

​
payment_type
string
Restrict results to a single payment type. Accepted values: loan, lease, ppa, cash.
​
term_months
number
Restrict results to a specific loan term in months.

​
Response Fields

​
metric
string
The metric key that was queried, echoed back in the response for verification, e.g. "dealer_fee".
​
label
string
The human-readable display name for the metric as defined in the benchmark registry, e.g. "Dealer fee".
​
unit
string
Formatting hint for the statistical values. One of "percent", "currency", or "number". Use this field to render values correctly in your UI (e.g. prefix $ for currency, append % for percent).
​
filters
object | null
An object containing the filter key-value pairs that were applied to the computation, or null if no filters were provided. Only filters recognized by the metric are included.
​
avg
number | null
Mean (arithmetic average) of all matching records. null if no data is available for the filter combination.
​
median
number | null
50th-percentile value. More robust than the mean in the presence of outliers.
​
min
number | null
Lowest observed value across all matching records.
​
max
number | null
Highest observed value across all matching records.
​
stddev
number | null
Population standard deviation, indicating spread around the mean. A higher value signals greater variability in the dataset.
​
p25
number | null
25th percentile (first quartile). 25% of records fall at or below this value.
​
p75
number | null
75th percentile (third quartile). 75% of records fall at or below this value. The interquartile range (p75 − p25) is a useful spread metric that excludes extreme outliers.
​
sample_size
integer
Number of records included in the computation after all filters were applied. A value of 0 means no matching data was found; all statistical fields will be null.
All statistical computations are performed against the filtered dataset at query time. Results reflect the current state of the catalog and are not cached.

​
Example Requests

curl "https://homeservicedata.com/api/v1/benchmarks?metric=dealer_fee" \
  -H "x-api-key: YOUR_API_KEY"

​
Response Example

The following shows a full response for metric=dealer_fee filtered to payment_type=loan and term_months=240: 
{
  "success": true,
  "data": {
    "metric": "dealer_fee",
    "label": "Dealer fee",
    "unit": "percent",
    "filters": {
      "payment_type": "loan",
      "term_months": "240"
    },
    "avg": 28.74,
    "median": 28.00,
    "min": 18.50,
    "max": 39.99,
    "stddev": 4.31,
    "p25": 25.50,
    "p75": 31.25,
    "sample_size": 312
  }
}
The p25–p75 interquartile range is the most reliable spread signal for pricing benchmarks. Outlier dealer fees at min and max often reflect promotional or corrective entries rather than typical market rates.

​
Dataset Access by Metric

Each metric requires a specific dataset scope to be enabled on your API key. Requesting a metric without the corresponding access returns a 403 Forbidden response.
MetricRequired Dataset
dealer_feefinancing
inverter_base_costhardware
inverter_price_per_watthardware
interest_ratefinancing

​
Error Responses

HTTP StatusCause
400 Bad Requestmetric parameter is missing, or the supplied key is not a recognized benchmark metric. The error message lists all valid metric keys.
401 UnauthorizedMissing or invalid x-api-key header.
403 ForbiddenYour API key does not have access to the dataset required by the requested metric.
500 Internal Server ErrorUnexpected server-side error — contact support if the issue persists.