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.com/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 Trade vertical. One of: hvac, solar, roofing, plumbing, electrical.
BLS SOC occupation code override (e.g., 49-9021). Overrides the default code for the selected trade.
Filter by geographic aggregation. One of: national, state, metro, nonmetro.
Two-letter state code (e.g., TX). Returns records where state_code matches.
BLS area code for a specific metro or non-metro area (e.g., C3518 for Dallas–Fort Worth).
Filter to a specific BLS survey year (e.g., 2023). Must be a four-digit integer greater than 2000.
When true, state-level records are included alongside metro/non-metro records.
When true, metro area records are included alongside state records.
Maximum number of records to return. Capped at 500.
Response Fields Array of regional labor rate objects. Unique record identifier.
Trade category for this record.
BLS SOC code (e.g., 49-9021).
Geographic region for this record. Region type: national, state, metro, or nonmetro.
State code, if applicable.
State name, if applicable.
Human-readable region name.
Estimated employment count for this occupation in the region.
BLS raw wage statistics. Show wage_distribution fields
10th percentile hourly wage.
25th percentile hourly wage.
75th percentile hourly wage.
90th percentile hourly wage.
Relative standard error of the employment estimate.
Percent relative standard error of the wage estimate.
Burden-adjusted labor cost rates for use in job costing. Labor burden multiplier applied to raw BLS wages.
Burden-loaded mean hourly cost.
Burden-loaded 25th percentile hourly cost.
Burden-loaded median hourly cost.
Burden-loaded 75th percentile hourly cost.
Source traceability. Internal source document reference.
URL to BLS OEWS data source.
URL to burden rate source.
ISO 8601 timestamp of last verification.
Always true for labor rate records.
Always published_labor_rate_source.
Occupation code used (default or explicit).
Most recent data year in the response.
Always true — all labor rate records are quote-safe.
Labor Adders GET https://homeservicedata.com/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 Trade vertical. One of: hvac, solar, roofing, plumbing, electrical.
Adder key to retrieve a single adder (e.g., crane_lift, attic_install). Slugified before matching.
Filter by quote-safe status. Omit to return all adders.
Maximum number of records to return. Capped at 500.
Response Fields Array of labor adder objects. Unique record identifier.
Trade category this adder applies to.
Normalized slug key for the adder (e.g., crane_lift).
Human-readable adder label.
Group or category the adder belongs to (e.g., access, line_set, refrigerant).
Unit of measure for this adder (e.g., per_unit, per_foot, per_job).
Whether the cost is a flat_fee, range, or formula.
Cost and labor-hour range estimates. Low end of total cost range in USD.
High end of total cost range in USD.
Low end of labor-hour estimate.
High end of labor-hour estimate.
Low end of material cost component in USD.
High end of material cost component in USD.
Description of the source or methodology used to derive this adder.
Free-text notes about how to apply this adder.
Conditions preventing this adder from reaching quote_safe: true.
Whether this adder is verified for use in customer-facing quotes.
Source traceability. Internal source document reference.
ISO 8601 timestamp of last verification.
Always labor_adder_context.
Adder key filter applied.
Number of adder records returned.
Whether results were restricted to quote-safe adders.
Description of the trust model for this dataset.
Example Requests Regional Labor Rates
Labor Adders
curl -G https://homeservicedata.com/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"
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." } } }
