Skip to main content
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.com/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

​
state
string
Two-letter state code (e.g., CA, FL). Case-insensitive.
​
city
string
City name. Partial match, case-insensitive.
​
utility
string
Utility provider name or slug. Partial match on name, exact match on slug.
​
lat
number
Latitude in decimal degrees. When combined with lng, results are sorted by distance from this point.
​
lng
number
Longitude in decimal degrees. Must be supplied together with lat.
​
quote_safe
boolean
When true, returns only records verified for quote-safe territory assignment.
​
limit
integer
default:"100"
Maximum number of records to return. Capped at 500.

​
Response Fields

​
records
array
Array of utility territory objects.
​
coverage
object
Query summary metadata.

​
Resolve Utility Territory from Address

GET https://homeservicedata.com/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

​
address
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.
​
limit
integer
default:"5"
Maximum number of matched territory records to return. Capped at 10.

​
Response Headers

HeaderDescription
X-HSD-Cachehit if the geocode result was served from cache, miss otherwise.
X-HSD-Resolution-Modecached 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:
​
geocode
object
Geocoding result for the submitted address.
​
territories
array
Ordered list of matched utility territory records. Structure mirrors the browse endpoint records.
​
resolution_method
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.com/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"

​
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."
    }
  }
}