GET /api/v1/catalog/equipment — Equipment Catalog

The Equipment Catalog endpoint lets you browse and filter the full global product database. Records span solar modules and inverters, HVAC systems, roofing materials, and generic hardware products. Each record includes base pricing, a trade-specific specs object, embedded pricing intelligence where available, and a provenance block that tells you exactly how trustworthy the record is. This is the right endpoint for building product pickers, populating quote-line dropdowns, and syncing your local product database.

Endpoint

GET https://homeservicedata.org/api/v1/catalog/equipment

Authentication

Requires a valid x-api-key header. The endpoint resolves the appropriate dataset key based on your trade and category filters, then checks your organization’s entitlement. A 403 is returned if your key lacks access to the resolved dataset.

Query Parameters

string

Filter by trade vertical. One of: solar, hvac, roofing, plumbing, electrical. Omit to browse across all trades your key is entitled to.

string

Filter by equipment category. One of: module, inverter, roofing, hvac, product. When a category is specified, the response includes a richer, category-specific specs object (see Category Specs below).

Category	Trade	Description
`module`	`solar`	Solar PV modules with STC/PTC ratings, dimensions, and cell data
`inverter`	`solar`	Solar inverters with pricing adjustments and default flags
`roofing`	`roofing`	Roofing materials with warranty, fire class, and exposure specs
`hvac`	`hvac`	HVAC systems with SEER2/EER2/HSPF2 ratings and AHRI certification
`product`	any	Generic hardware and products without a category-specific spec table

string

Case-insensitive substring filter on the manufacturer name. For example, manufacturer=Goodman matches "Goodman Manufacturing" and "Goodman/Daikin".

string

Case-insensitive substring filter on the SKU or model number. For example, sku=GSX140 matches "Goodman GSX14024" and "GSX14036".

integer

Page number to retrieve, 1-indexed. Default 1.

integer

Number of records per page. Minimum 1, maximum 100, default 25. Results are ordered by manufacturer ascending, then sku ascending.

Request Examples

GET /api/v1/catalog/equipment?trade=hvac&category=hvac&per_page=25 HTTP/1.1
Host: homeservicedata.org
x-api-key: YOUR_API_KEY

GET /api/v1/catalog/equipment?manufacturer=Goodman&sku=GSX14 HTTP/1.1
Host: homeservicedata.org
x-api-key: YOUR_API_KEY

GET /api/v1/catalog/equipment?trade=solar&category=module&page=2&per_page=50 HTTP/1.1
Host: homeservicedata.org
x-api-key: YOUR_API_KEY

TypeScript example

const params = new URLSearchParams({
  trade: "hvac",
  category: "hvac",
  manufacturer: "Goodman",
  page: "1",
  per_page: "25",
});

const response = await fetch(
  `https://homeservicedata.org/api/v1/catalog/equipment?${params}`,
  { headers: { "x-api-key": process.env.HSD_API_KEY! } }
);

const { data, error, meta } = await response.json();
if (error) throw new Error(error);
// data is ProductEquipmentRecord[]
// meta.total_pages tells you how many pages remain

Response

{
  "data": [
    {
      "record_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "trade": "hvac",
      "category": "hvac",
      "manufacturer": "Goodman",
      "sku": "GSX14024",
      "base_cost": 1240.00,
      "is_archived": false,
      "pricing": {
        "observed_public_price": 1310.00,
        "estimated_base_cost": 1240.00,
        "estimated_installed_price_low": 3800.00,
        "estimated_installed_price_high": 5200.00,
        "contractor_gross_margin_assumption": 0.35,
        "confidence": "high",
        "method": "price_observation_model",
        "model_version": "v2",
        "observation_count": 14,
        "source_document_id": "f9e8d7c6-...",
        "last_verified_at": "2024-11-20T00:00:00.000Z",
        "notes": null
      },
      "specs": {
        "seer2_rating": 15.2,
        "eer2_rating": 12.5,
        "tonnage": 2.0,
        "refrigerant_type": "R-410A",
        "cooling_capacity_btu_h": 24000,
        "compressor_staging": "single",
        "ahri_reference_number": "207845123",
        "cold_climate": false,
        "energy_star_model_identifier": "Goodman+GSX14024",
        "date_certified": "2023-06-15",
        "source_url": "https://www.ahridirectory.org/..."
      },
      "provenance": {
        "source_document_id": "f9e8d7c6-...",
        "approval_state": "published",
        "last_verified_at": "2024-11-20T00:00:00.000Z",
        "quote_safe": true,
        "trust_basis": "catalog_record"
      }
    }
  ],
  "error": null,
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 342,
    "total_pages": 14
  }
}

Equipment Record Fields

string

Stable UUID for this equipment record. Use this to reference the record in quote line items and downstream systems.

string

The trade vertical: solar, hvac, roofing, plumbing, or electrical.

string

The equipment category: module, inverter, roofing, hvac, or product.

string

The manufacturer or brand name.

string

The manufacturer model number or SKU.

number

The catalog base cost in USD. This is the platform’s internal cost basis and may differ from observed market prices. Use pricing.estimated_base_cost for quote calculations when available.

boolean

true when the product has been discontinued or removed from active quoting. Archived records are excluded by default unless include_archived=true is passed. Archived records always have provenance.quote_safe: false.

object | null

Embedded pricing intelligence derived from market price observations. null when no pricing data has been collected for this record.

Show pricing fields

number | null

The most recently observed public market price in USD. null if no direct observation exists.

number | null

The platform’s modeled estimate of distributor cost in USD. Use this for equipment line items in quote calculations.

number | null

Low end of the estimated fully installed price range in USD.

number | null

High end of the estimated fully installed price range in USD.

number | null

The gross margin assumption used in the installed price model, expressed as a decimal (e.g. 0.35 = 35%).

string | null

Pricing confidence tier: high, medium, or low.

string | null

The name of the pricing model or method used to derive estimates.

string | null

Version string of the pricing model.

number

Number of market price observations that informed this record’s pricing estimates.

string | null

UUID of the source document that contributed the pricing data.

string | null

ISO 8601 timestamp of the most recent pricing verification.

string | null

Free-text notes from the pricing analyst, if any.

object

Category-specific technical specifications. The shape of this object varies by category — see Category-Specific Specs below. An empty object {} is returned for product category records or when no spec record exists.

object

Data lineage and trust metadata for this record.

Show provenance fields

string | null

UUID of the source document this record was ingested from.

string

Always "published" for records returned by this endpoint.

string | null

ISO 8601 timestamp of the most recent source verification.

boolean

true when the record is approved for use in customer-facing quotes. Active (non-archived) catalog records are quote_safe: true.

string

Always "catalog_record" for equipment records, indicating the record originates from a curated, reviewed catalog entry.

The `quote_safe` Flag on Equipment Records

For equipment catalog records, quote_safe is derived directly from is_archived. Any active, non-archived record is quote_safe: true. If you need to enforce this in your UI without calling provenance.quote_safe, check is_archived === false.

The catalog does not require quote_safe as a filter parameter — the default behavior (excluding archived records) already ensures all returned records are quote-ready. If you are building a product management tool that needs to display discontinued items, pass include_archived=true and handle the is_archived flag in your UI.

Category-Specific Specs

When you filter by category, the specs object on each record contains the full set of fields for that category. Without a category filter, a summarized subset is returned.

module

rating_stc, rating_ptc, efficiency, voc, isc, vmp, imp, length_mm, width_mm, weight_kg, product_warranty_years, frame_color, backsheet_color, cell_quantity, temp_coeff_pmax, pan_file_url

inverter

external_id, labor_adjustment, price_adjustment, price_adjustment_per_watt, is_default, price_adjustment_per_panel

roofing

material_type, warranty_years, wind_rating_mph, fire_class, impact_rating_class, exposure_inches, bundles_per_square, weight_per_square_lbs, algae_resistance_years, citation_url

hvac

seer2_rating, eer2_rating, hspf2_rating, tonnage, refrigerant_type, cooling_capacity_btu_h, compressor_staging, cold_climate, ahri_reference_number, energy_star_model_identifier, date_certified, source_url (full list includes heating capacities at 47°F/17°F/5°F, COP, and all AHRI certification fields)

Always pass category when you know the type of equipment you need. This enables an inner join against the spec table, which filters out any records that do not have a spec entry — ensuring every record in the response has a fully populated specs object.

Errors

Status	Message	Cause
`400`	`Unsupported category "…". Use module, inverter, roofing, hvac, or product.`	`category` value not in the allowed set
`400`	`Unsupported trade "…". Use solar, roofing, hvac, plumbing, or electrical.`	`trade` value not in the allowed set
`403`	`Dataset access required: … requires production access.`	Key lacks entitlement for the resolved dataset
`401`	`Missing x-api-key header.`	No API key provided
`500`	`Internal server error.`	Unexpected database error — retry with backoff

Search — Find equipment by name or SKU without knowing the category upfront, alongside results from other dataset types.
Quote Context (/api/v1/quote-context) — Returns a pre-assembled, quote-ready bundle that includes recommended equipment options, finance programs, incentives, and utility rates for a specific address and trade. Use this instead of the catalog endpoint when building a quote flow that needs fully contextualized data.
Hardware Inverters (/api/v1/hardware/inverters) — A legacy endpoint that returns solar inverter records in the original InverterRecord shape. New integrations should prefer the catalog endpoint with category=inverter.

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/catalog/equipment — Equipment Catalog

Endpoint

Authentication

Query Parameters

Request Examples

Response

Equipment Record Fields

The `quote_safe` Flag on Equipment Records

Category-Specific Specs

module

inverter

roofing

hvac

Errors

​Endpoint

​Authentication

​Query Parameters

​Request Examples

​Response

​Equipment Record Fields

​The quote_safe Flag on Equipment Records

​Category-Specific Specs

module

inverter

roofing

hvac

​Errors

​Related Endpoints

Endpoint

Authentication

Query Parameters

Request Examples

Response

Equipment Record Fields

The `quote_safe` Flag on Equipment Records

Category-Specific Specs

Errors

Related Endpoints