GET /api/v1/context/climate — County Climate Data

The climate context endpoint returns county-level climate and weather-normal data used to support HVAC equipment sizing, load calculations, and incentive eligibility checks. Records draw from DOE/PNNL county climate-zone assignments and NOAA 1991–2020 station normals. The primary fields — IECC climate zone, HDD/CDD, and design temperatures — are quote_safe: true when backed by confirmed station matches. Design-temperature proxy values derived from NOAA hourly percentiles are provided as supplemental context and always carry quote_safe: false. Endpoint

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

Query Parameters

string

Two-letter state code (e.g., TX, MN). Case-insensitive.

string

County name. Partial match, case-insensitive (e.g., Travis, Cook).

string

5-digit county FIPS code (e.g., 48453 for Travis County, TX). Exact match.

boolean

When true, returns only records verified for quote use. When false, returns unverified/context-only records.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Response Fields

array

Array of county climate context objects.

Show Record fields

string

Unique record identifier.

object

Geographic identifiers for the county.

Show geography fields

string

Two-letter state code.

string

County name.

string

5-digit county FIPS code.

object

Climate zone and weather-normal values.

Show climate fields

string

IECC 2021 climate zone designation (e.g., 3A, 5B).

string | null

DOE Building America climate region label.

string | null

Moisture regime: dry, moist, marine, or unknown.

boolean

Whether the county qualifies as a cold or very cold climate zone.

string | null

NOAA normal period used (e.g., 1991-2020).

integer | null

Annual heating degree days base 65°F.

integer | null

Annual cooling degree days base 65°F.

number | null

ACCA Manual J design heating temperature in °F (quote-safe when station-matched).

number | null

ACCA Manual J design cooling temperature in °F (quote-safe when station-matched).

object

NOAA hourly percentile proxy values — supplemental context only, never quote-safe.

Show proxy fields

number | null

Heating design temperature proxy derived from NOAA hourly normals.

number | null

Cooling design temperature proxy derived from NOAA hourly normals.

string | null

Percentile method used to derive the proxy value.

boolean

Always false for proxy values.

array

List of unresolved conditions preventing quote-safe status.

object

Details of the matched NOAA weather station.

Show station_match fields

string | null

NOAA station identifier.

string | null

Human-readable station name.

number | null

Distance in miles from the county centroid to the matched station.

string | null

Station-matching method used.

string | null

Confidence tier for this station match.

string | null

URL to the station data source.

string | null

ISO 8601 timestamp of last station-match verification.

object

URLs to underlying source documents.

Show source_links fields

string | null

URL to the county climate-zone context source.

string | null

URL to NOAA annual normals data.

string | null

URL to NOAA monthly normals data.

string | null

URL to NOAA hourly normals data (basis of proxy values).

array

List of conditions preventing this record from reaching quote_safe: true.

boolean

Whether this record is cleared for use in customer-facing quotes.

string | null

Confidence tier: high, medium, or low.

object

Source traceability metadata.

Show provenance fields

string | null

Internal source document reference.

string | null

Canonical source URL.

string | null

ISO 8601 timestamp of last verification.

string

Always climate_design_context.

object

Query summary metadata.

Show Coverage fields

string | null

State filter applied.

string | null

County filter applied.

string | null

FIPS filter applied.

integer

Number of records returned.

boolean

Whether results were restricted to quote-safe records.

string

Description of the trust model for this dataset.

design_temperature_proxy values inside each record are derived from NOAA hourly percentile data and are always quote_safe: false. Do not use them as authoritative design temperatures in Manual J load calculations without independent verification.

Example Request

curl -G https://homeservicedata.org/api/v1/context/climate \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "state=TX" \
  --data-urlencode "county=Travis" \
  --data-urlencode "quote_safe=true"

Example Response

{
  "success": true,
  "data": {
    "records": [
      {
        "record_id": "clm_01hzka1bc2de3fg4hi5jk6abcd",
        "geography": {
          "state_code": "TX",
          "county_name": "Travis",
          "county_fips": "48453"
        },
        "climate": {
          "iecc_climate_zone": "2A",
          "building_america_region": "Hot-Humid",
          "moisture_regime": "moist",
          "cold_climate_flag": false,
          "noaa_normal_period": "1991-2020",
          "hdd_65": 1648,
          "cdd_65": 3114,
          "design_heating_temp_f": 26.0,
          "design_cooling_temp_f": 99.0,
          "design_temperature_proxy": {
            "heating_temp_f": 24.5,
            "cooling_temp_f": 100.2,
            "basis": "noaa_hourly_p99",
            "quote_safe": false,
            "unresolved_requirements": ["proxy_values_not_verified_for_quote_use"]
          }
        },
        "station_match": {
          "nearest_station_id": "USW00013958",
          "nearest_station_name": "Austin Bergstrom International Airport",
          "distance_miles": 4.7,
          "method": "centroid_nearest",
          "confidence": "high",
          "source_url": "https://www.ncei.noaa.gov/",
          "last_verified_at": "2024-09-01T00:00:00Z"
        },
        "source_links": {
          "county_context_url": "https://www.energy.gov/eere/buildings/climate-zones",
          "noaa_annual_normals_url": "https://www.ncei.noaa.gov/access/us-climate-normals/",
          "noaa_monthly_normals_url": null,
          "noaa_hourly_normals_url": null
        },
        "unresolved_requirements": [],
        "quote_safe": true,
        "confidence": "high",
        "provenance": {
          "source_document_id": "doc_01hzka1bc2de3fg4hi5jk6xyz",
          "source_url": "https://www.energy.gov/eere/buildings/climate-zones",
          "last_verified_at": "2024-09-01T00:00:00Z",
          "trust_basis": "climate_design_context"
        }
      }
    ],
    "coverage": {
      "state": "TX",
      "county": "Travis",
      "county_fips": null,
      "records_returned": 1,
      "quote_safe_only": true,
      "trust_basis": "DOE/PNNL county climate-zone context plus NOAA 1991-2020 station normals. NOAA hourly percentile values are exposed only as non-quote-safe design-temperature proxies."
    }
  }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/climate — County Climate Data

Query Parameters

Response Fields

Example Request

Example Response

​Query Parameters

​Response Fields

​Example Request

​Example Response

Query Parameters

Response Fields

Example Request

Example Response