GET /api/v1/context/labor — Labor Rates and Adders

The labor endpoints provide two complementary datasets for building accurate cost models. Regional labor rates (/api/v1/context/labor) deliver BLS Occupational Employment and Wage Statistics (OEWS) wage distributions by trade, geography, and occupation code — all records in this dataset are quote_safe: true. Labor adders (/api/v1/context/labor-adders) provide per-task cost and labor-hour ranges for installation complexity factors (crane lifts, attic work, line sets, etc.) and carry their own quote_safe flags based on source determinism.

Regional Labor Rates

GET https://homeservicedata.org/api/v1/context/labor

Returns BLS OEWS wage records for the specified trade and geography. Results default to the standard occupation code for the requested trade (HVAC: 49-9021, Roofing: 47-2181, Electrical: 47-2111, Plumbing: 47-2152, Solar: 47-2231).

Query Parameters

string

default:"hvac"

Trade vertical. One of: hvac, solar, roofing, plumbing, electrical.

string

BLS SOC occupation code override (e.g., 49-9021). Overrides the default code for the selected trade.

string

Filter by geographic aggregation. One of: national, state, metro, nonmetro.

string

Two-letter state code (e.g., TX). Returns records where state_code matches.

string

BLS area code for a specific metro or non-metro area (e.g., C3518 for Dallas–Fort Worth).

integer

Filter to a specific BLS survey year (e.g., 2023). Must be a four-digit integer greater than 2000.

boolean

default:"false"

When true, state-level records are included alongside metro/non-metro records.

boolean

default:"false"

When true, metro area records are included alongside state records.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Response Fields

array

Array of regional labor rate objects.

Show Record fields

string

Unique record identifier.

string

Trade category for this record.

string

BLS SOC code (e.g., 49-9021).

string

BLS occupation title.

object

Geographic region for this record.

Show region fields

string

Region type: national, state, metro, or nonmetro.

string

BLS area code.

string | null

State code, if applicable.

string | null

State name, if applicable.

string

Human-readable region name.

integer

BLS survey year.

string

Survey period label.

integer | null

Estimated employment count for this occupation in the region.

object

BLS raw wage statistics.

Show wage_distribution fields

number | null

Mean hourly wage.

number | null

10th percentile hourly wage.

number | null

25th percentile hourly wage.

number | null

Median hourly wage.

number | null

75th percentile hourly wage.

number | null

90th percentile hourly wage.

integer | null

Median annual wage.

number | null

Relative standard error of the employment estimate.

number | null

Percent relative standard error of the wage estimate.

object

Burden-adjusted labor cost rates for use in job costing.

Show loaded_labor fields

number | null

Labor burden multiplier applied to raw BLS wages.

number | null

Burden-loaded mean hourly cost.

number | null

Burden-loaded 25th percentile hourly cost.

number | null

Burden-loaded median hourly cost.

number | null

Burden-loaded 75th percentile hourly cost.

object

Source traceability.

Show provenance fields

string | null

Internal source document reference.

string | null

URL to BLS OEWS data source.

string | null

URL to burden rate source.

string

ISO 8601 timestamp of last verification.

boolean

Always true for labor rate records.

string

Always published_labor_rate_source.

object

Show Coverage fields

string

Trade filter applied.

string

Occupation code used (default or explicit).

string

Always BLS OEWS.

integer | null

Most recent data year in the response.

boolean

Always true — all labor rate records are quote-safe.

Labor Adders

GET https://homeservicedata.org/api/v1/context/labor-adders

Returns per-task labor and material cost adders — complexity factors added on top of base labor rates to account for job-specific conditions such as attic installs, crane lifts, or extended line sets.

Query Parameters

string

default:"hvac"

Trade vertical. One of: hvac, solar, roofing, plumbing, electrical.

string

Adder key to retrieve a single adder (e.g., crane_lift, attic_install). Slugified before matching.

boolean

Filter by quote-safe status. Omit to return all adders.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Response Fields

array

Array of labor adder objects.

Show Record fields

string

Unique record identifier.

string

Trade category this adder applies to.

string

Normalized slug key for the adder (e.g., crane_lift).

string

Human-readable adder label.

string | null

Group or category the adder belongs to (e.g., access, line_set, refrigerant).

string | null

Unit of measure for this adder (e.g., per_unit, per_foot, per_job).

string | null

Whether the cost is a flat_fee, range, or formula.

object

Cost and labor-hour range estimates.

Show ranges fields

number | null

Low end of total cost range in USD.

number | null

High end of total cost range in USD.

number | null

Low end of labor-hour estimate.

number | null

High end of labor-hour estimate.

number | null

Low end of material cost component in USD.

number | null

High end of material cost component in USD.

string | null

Description of the source or methodology used to derive this adder.

string | null

Free-text notes about how to apply this adder.

array

Conditions preventing this adder from reaching quote_safe: true.

boolean

Whether this adder is verified for use in customer-facing quotes.

string | null

Confidence tier.

object

Source traceability.

Show provenance fields

string | null

Internal source document reference.

string | null

Source URL.

string | null

ISO 8601 timestamp of last verification.

string

Always labor_adder_context.

object

Show Coverage fields

string

Trade filter applied.

string | null

Adder key filter applied.

integer

Number of adder records returned.

boolean

Whether results were restricted to quote-safe adders.

string

Description of the trust model for this dataset.

Example Requests

curl -G https://homeservicedata.org/api/v1/context/labor \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=TX" \
  --data-urlencode "region_type=metro" \
  --data-urlencode "limit=5"

curl -G https://homeservicedata.org/api/v1/context/labor-adders \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "quote_safe=true" \
  --data-urlencode "limit=10"

Example Response — Labor Adders

{
  "success": true,
  "data": {
    "records": [
      {
        "record_id": "adr_01hzka1bc2de3fg4hi5jk6uvwx",
        "trade": "hvac",
        "adder_key": "crane_lift",
        "adder_label": "Crane Lift",
        "adder_group": "access",
        "unit": "per_job",
        "amount_type": "range",
        "ranges": {
          "cost_low": 350.00,
          "cost_high": 900.00,
          "labor_hours_low": 2.0,
          "labor_hours_high": 4.0,
          "material_cost_low": null,
          "material_cost_high": null
        },
        "source_basis": "Contractor survey and published service-area crane rental rates.",
        "calculation_notes": "Apply when equipment must be lifted to roof or second-floor mechanical room.",
        "unresolved_requirements": [],
        "quote_safe": true,
        "confidence": "medium",
        "provenance": {
          "source_document_id": "doc_01hzka1bc2de3fg4hi5jk6lbr",
          "source_url": null,
          "last_verified_at": "2024-07-01T00:00:00Z",
          "trust_basis": "labor_adder_context"
        }
      }
    ],
    "coverage": {
      "trade": "hvac",
      "adder": null,
      "records_returned": 1,
      "quote_safe_only": true,
      "trust_basis": "Adder records are context ranges or labor-hour assumptions unless an official deterministic fee source is loaded."
    }
  }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/labor — Labor Rates and Adders

Regional Labor Rates

Query Parameters

Response Fields

Labor Adders

Query Parameters

Response Fields

Example Requests

Example Response — Labor Adders

​Regional Labor Rates

​Query Parameters

​Response Fields

​Labor Adders

​Query Parameters

​Response Fields

​Example Requests

​Example Response — Labor Adders

Regional Labor Rates

Query Parameters

Response Fields

Labor Adders

Query Parameters

Response Fields

Example Requests

Example Response — Labor Adders