GET /api/v1/context/utility-territory — Lookup API

The utility territory endpoints let you look up which electric utility serves a given location. The browse endpoint (GET /api/v1/context/utility-territory) returns territory records you can filter by state, city, utility name, or lat/lng coordinates. The resolve endpoint (GET /api/v1/context/utility-territory/resolve) accepts a full postal address, geocodes it, and returns the best-matched service territory records ordered by confidence. Quote-safe territory resolution requires polygon-level coverage to be loaded for the target area — records backed only by sample-point context return with quote_safe: false.

Browse Utility Territories

GET https://homeservicedata.org/api/v1/context/utility-territory

Use this endpoint to explore which utilities operate in a state or city, or to find territories near a GPS coordinate.

Query Parameters

string

Two-letter state code (e.g., CA, FL). Case-insensitive.

string

City name. Partial match, case-insensitive.

string

Utility provider name or slug. Partial match on name, exact match on slug.

number

Latitude in decimal degrees. When combined with lng, results are sorted by distance from this point.

number

Longitude in decimal degrees. Must be supplied together with lat.

boolean

When true, returns only records verified for quote-safe territory assignment.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Response Fields

array

Array of utility territory objects.

Show Record fields

string

Unique record identifier.

object

Provider-level details for the utility.

Show utility fields

string

Internal utility provider ID.

string | null

Utility display name (e.g., Pacific Gas and Electric).

string | null

Normalized slug (e.g., pacific-gas-and-electric).

string | null

EIA utility identifier.

string

Provider type: iou, municipal, cooperative, federal, or unknown.

array

List of state codes the utility operates in.

object

Geographic coverage details for this territory record.

Show geography fields

string

State code for this territory.

string | null

County name, if territory is county-scoped.

string | null

5-digit county FIPS code.

string | null

City name, if territory is city-scoped.

string | null

ZIP code, if territory is ZIP-scoped.

string

Granularity of this record: state, county, city, zip, or polygon.

number | null

Representative latitude for the coverage area.

number | null

Representative longitude for the coverage area.

string | null

Example address within the territory.

number | null

Distance in miles from the supplied lat/lng to the sample point. null if coordinates were not supplied.

string | null

Free-text notes about boundary edge cases or service conditions.

string | null

Status of polygon geometry loading: loaded, pending, unavailable.

boolean

Whether this record meets the threshold for use in customer-facing quotes.

string | null

Confidence tier: high, medium, or low.

object

Source traceability fields.

Show provenance fields

string | null

Internal source document reference.

string | null

Source data URL.

string | null

URL to the utility’s own territory map or data page.

string | null

ISO 8601 timestamp of last verification.

string

Always utility_territory_context.

object

Query summary metadata.

Show Coverage fields

integer

Number of records returned.

string | null

State filter applied.

string | null

City filter applied.

string | null

Utility filter applied.

boolean

Whether lat/lng sorting was applied.

boolean

Whether results were restricted to quote-safe records.

string

Description of the trust model for this dataset.

Resolve Utility Territory from Address

GET https://homeservicedata.org/api/v1/context/utility-territory/resolve

Geocodes a postal address and returns the best-matched utility territory records. This endpoint performs a live geocode lookup when the address is not already in the resolver cache, so it counts against your resolve budget.

The resolve endpoint has a per-key resolve budget in addition to the standard rate limit. Each live geocode call (cache miss) decrements your budget. Cached responses (indicated by X-HSD-Cache: hit) do not consume budget. Contact support to increase your resolve quota.

Query Parameters

string

required

Full postal address to resolve (e.g., 1600 Pennsylvania Ave NW, Washington, DC 20500). Maximum 300 characters. Must be a postal address, not a URL or coordinate string.

integer

default:"5"

Maximum number of matched territory records to return. Capped at 10.

Response Headers

Header	Description
`X-HSD-Cache`	`hit` if the geocode result was served from cache, `miss` otherwise.
`X-HSD-Resolution-Mode`	`cached` or `live` — mirrors cache status.

Response Fields

The response body is the full resolution object returned by the utility territory resolver. Key top-level fields:

object

Geocoding result for the submitted address.

Show geocode fields

boolean

Whether the address was successfully geocoded.

string | null

Canonical form of the address returned by the geocoder.

number | null

Geocoded latitude.

number | null

Geocoded longitude.

string | null

Geocode confidence: rooftop, range_interpolated, geometric_center, or approximate.

array

Ordered list of matched utility territory records. Structure mirrors the browse endpoint records.

string | null

Method used to match the geocoded point to territories (e.g., polygon_lookup, sample_point_nearest).

A 422 status is returned when the address could not be geocoded. This still counts as a resolve attempt. Validate addresses client-side before calling this endpoint at scale.

Example Requests

curl -G https://homeservicedata.org/api/v1/context/utility-territory \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "state=CA" \
  --data-urlencode "city=San Jose" \
  --data-urlencode "quote_safe=true" \
  --data-urlencode "limit=5"

curl -G "https://homeservicedata.org/api/v1/context/utility-territory/resolve" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "address=1600 Pennsylvania Ave NW, Washington, DC 20500" \
  --data-urlencode "limit=3"

Example Responses

{
  "success": true,
  "data": {
    "records": [
      {
        "record_id": "utl_01hzka1bc2de3fg4hi5jk6mnop",
        "utility": {
          "id": "prv_01hzka1bc2de3fg4hi5abcde",
          "name": "Pacific Gas and Electric",
          "slug": "pacific-gas-and-electric",
          "eia_utility_id": "14328",
          "provider_type": "iou",
          "state_codes": ["CA"]
        },
        "geography": {
          "state_code": "CA",
          "county_name": "Santa Clara",
          "county_fips": "06085",
          "city_name": "San Jose",
          "zip_code": null,
          "coverage_level": "city",
          "sample_lat": 37.3382,
          "sample_lng": -121.8863,
          "sample_address": "100 W Santa Clara St, San Jose, CA 95113",
          "distance_miles": null
        },
        "territory_notes": null,
        "geometry_status": "loaded",
        "quote_safe": true,
        "confidence": "high",
        "provenance": {
          "source_document_id": "doc_01hzka1bc2de3fg4hi5xyz",
          "source_url": "https://www.pge.com/en_US/residential/home.page",
          "provider_source_url": "https://www.pge.com/maps",
          "last_verified_at": "2024-10-01T00:00:00Z",
          "trust_basis": "utility_territory_context"
        }
      }
    ],
    "coverage": {
      "records_returned": 1,
      "state": "CA",
      "city": "San Jose",
      "utility": null,
      "coordinates_used": false,
      "quote_safe_only": true,
      "trust_basis": "Sample-point utility context from NREL; polygon service territories must be loaded before quote-safe address resolution."
    }
  }
}

{
  "success": true,
  "data": {
    "geocode": {
      "matched": true,
      "normalized_address": "1600 Pennsylvania Ave NW, Washington, DC 20500, USA",
      "lat": 38.8977,
      "lng": -77.0366,
      "confidence": "rooftop"
    },
    "territories": [
      {
        "record_id": "utl_01hzka1bc2de3fg4hi5jk6dcde",
        "utility": {
          "id": "prv_01hzka1bc2de3fg4hi5dcdce",
          "name": "Pepco",
          "slug": "pepco",
          "eia_utility_id": "13781",
          "provider_type": "iou",
          "state_codes": ["DC", "MD"]
        },
        "geography": {
          "state_code": "DC",
          "county_name": null,
          "county_fips": null,
          "city_name": "Washington",
          "zip_code": "20500",
          "coverage_level": "polygon",
          "sample_lat": 38.8977,
          "sample_lng": -77.0366,
          "sample_address": null,
          "distance_miles": 0.0
        },
        "territory_notes": null,
        "geometry_status": "loaded",
        "quote_safe": true,
        "confidence": "high",
        "provenance": {
          "source_document_id": "doc_01hzka1bc2de3fg4hi5dcxyz",
          "source_url": "https://www.pepco.com",
          "provider_source_url": "https://www.pepco.com/home/serviceterritories",
          "last_verified_at": "2024-09-15T00:00:00Z",
          "trust_basis": "utility_territory_context"
        }
      }
    ],
    "resolution_method": "polygon_lookup"
  }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/utility-territory — Lookup API

Browse Utility Territories

Query Parameters

Response Fields

Resolve Utility Territory from Address

Query Parameters

Response Headers

Response Fields

Example Requests

Example Responses

​Browse Utility Territories

​Query Parameters

​Response Fields

​Resolve Utility Territory from Address

​Query Parameters

​Response Headers

​Response Fields

​Example Requests

​Example Responses

Browse Utility Territories

Query Parameters

Response Fields

Resolve Utility Territory from Address

Query Parameters

Response Headers

Response Fields

Example Requests

Example Responses