Skip to main content
The Home Service Data REST API gives quoting tools, CRMs, and sales platforms programmatic access to structured, source-verified data across five home-service trades. Every response is wrapped in a consistent envelope, every data row carries readiness signals, and the API is versioned so your integration stays stable as the dataset grows.

​
Base URL

All API endpoints are served from a single base URL. The current stable version is v1. 
https://homeservicedata.com/api/v1
Always use HTTPS. HTTP requests are not supported. Append endpoint paths directly to the base URL — for example, https://homeservicedata.com/api/v1/search.

​
Authentication

Every request must include your API key in the x-api-key request header. There are no bearer tokens or cookies — the header is the sole authentication mechanism. 
GET /api/v1/search?q=Goodman HTTP/1.1
Host: homeservicedata.com
x-api-key: YOUR_API_KEY
API keys are organization-scoped. A key issued to your organization inherits the dataset entitlements that have been provisioned for that organization. Some keys carry additional per-key scope restrictions that cap access to a subset of those entitlements.
Keep your API key out of client-side code and version control. Rotate it immediately if it is exposed. See the Authentication guide for key management details.

​
Response Envelope

Every API response — whether successful or not — is wrapped in a standard three-field envelope. 
{
  "data": [ ... ],
  "error": null,
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}
​
data
array | object | null
The payload returned by the endpoint. null on error responses.
​
error
string | null
A human-readable error message. null on success responses. See Errors for the full list of error codes and messages.
​
meta
object | null
Pagination context on list endpoints, null on error responses and on endpoints that do not paginate.
An error response looks like this: 
{
  "data": null,
  "error": "Missing x-api-key header.",
  "meta": null
}

​
Pagination

List endpoints accept page and per_page query parameters. The default is page=1 and per_page=25. The maximum per_page is 100. 
GET /api/v1/catalog/equipment?trade=hvac&page=2&per_page=50
Iterate through pages by incrementing page until page exceeds meta.total_pages.

​
Data Quality Signals

Every data row that can be used in a quote carries at least two readiness signals. These are not decorative — they drive which records are safe to surface to customers.

quote_safe

true when the record has passed all validation checks and is approved for use in customer-facing quotes. Always filter on quote_safe=true in production quote flows.

confidence

A three-tier signal — high, medium, or low — indicating how closely the data matches a primary source. Higher confidence means fewer assumptions.

last_verified_at

ISO 8601 timestamp of the most recent source verification. Stale records may still be quote_safe but their confidence will reflect the age.

source_url

The canonical URL of the original source document or data sheet, where available. Useful for audit trails and compliance review.

​
Supported Trades

The API is organized around trade verticals. Pass the trade parameter to scope results to a single vertical.
Tradetrade value
Solarsolar
HVAChvac
Roofingroofing
Plumbingplumbing
Electricalelectrical
Some endpoints (utility territory, climate, permits) serve cross-trade context data. Those records carry trade: "context" in their responses.

​
Versioning

The API uses URL-path versioning. The current version is v1. Breaking changes will be released under a new version prefix (/api/v2/…) with a documented migration period. Non-breaking additions — new fields, new optional parameters, new endpoint groups — may be added to v1 without a version bump.

​
Endpoint Groups

Finance

Dealer fee programs, interest rates, term structures, and lender integrations. Requires finance_fees production access.

Equipment / Hardware

The full equipment catalog: solar modules, inverters, HVAC systems, roofing products, and generic hardware. Paginated browsing with category, manufacturer, and SKU filters.

Context

Location-aware context data — utility territories, electricity rates, incentive programs, permit assumptions, climate zones, and labor adders. Feed address-level data into quotes.

Sync

Dataset snapshots for bulk integration. Pull versioned exports of any entitled dataset into your own data store for offline use.

Search

Unified full-text search across all dataset types — equipment, finance programs, incentives, utilities, permits, labor, and source documents — in a single request.

Benchmarks

Statistical aggregates (average, median, P25/P75, std dev) for pricing and performance metrics, filterable by trade, region, and time window.

Quote Context

A single composite endpoint that assembles all quote-ready context for a given address and trade: equipment options, finance programs, incentives, utility rates, and permit requirements — deduplicated and quote_safe filtered.

​
Response Timing Headers

Every response includes an X-HSD-Duration-Ms header reporting the server-side processing time in milliseconds, and a Server-Timing header with per-phase breakdowns (auth, database, access checks, search). These are useful for diagnosing latency in production integrations.

​
Further Reading

  • Authentication — API key management, scopes, and rotation
  • Error Codes — HTTP status codes, error messages, and retry strategy