Developer Reference

API Documentation

Programmatic access to verified US service cost data across 8 verticals and 369 metros. All data traces to official government and verified industry sources.

Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header.

Authorization: Bearer {your-api-key}

API keys are issued on request. To obtain a key, contact us at contact@costfinder.ai with your intended use case and expected request volume.

Rate Limits

Rate limits are enforced per API key on a rolling 24-hour window. Exceeding your limit returns a 429 Too Many Requests response with the reset time in the error message.

Tier	Daily Limit	Intended Use
Free	100 req/day	Evaluation and personal projects
Basic	1,000 req/day	Small applications and integrations
Enterprise	Custom	High-volume production systems

Endpoints

GET/api/v1/costs

Returns verified cost ranges for a specified service, optionally filtered to a single location. Results respect the data density gate — only cross-referenced figures are returned. Maximum 100 results per request.

Query Parameters

Parameter	Type	Required	Description
`service`	string	Yes	Service slug (e.g., `roof-replacement`)
`location`	string	No	Location slug — state (e.g., `california`) or city (e.g., `los-angeles-ca`). Omit to return all available locations.

Example Request

curl -X GET "https://www.costfinder.ai/api/v1/costs?service=roof-replacement&location=california" \
  -H "Authorization: Bearer your-api-key"

Response Format

All responses are JSON. Cost values are returned as decimal strings to preserve precision. The sourceCount field indicates how many independent data sources contributed to the cost range — a higher count means higher confidence.

{
  "service": "roof-replacement",
  "location": "all",
  "tier": "free",
  "results": [
    {
      "serviceSlug": "roof-replacement",
      "serviceName": "Roof Replacement",
      "category": "home-services",
      "locationSlug": "california",
      "locationName": "California",
      "locationType": "state",
      "stateCode": "CA",
      "costLow": "4840.50",
      "costHigh": "20295.50",
      "costAverage": "8924.90",
      "sourceCount": 3,
      "sourceSlugs": "bls,homeadvisor,homeguide",
      "calculatedAt": "2026-06-18T22:09:23.964Z"
    }
  ],
  "count": 1
}

Error Codes

400

Bad Request

Missing or invalid required parameters.

401

Unauthorized

Missing, empty, or invalid API key.

429

Too Many Requests

Daily rate limit exceeded for your tier.

500

Internal Server Error

Unexpected server-side error. Contact support if it persists.

Need Higher Rate Limits or Enterprise Access?

For custom rate limits, bulk data licensing, or enterprise integrations, contact us at contact@costfinder.ai with your use case and expected request volume. We respond within 2 business days.