States API

The states endpoints provide jurisdiction-level overviews and detailed regulatory profiles.

GET /v1/states

List all 50 states and DC with regulation summary statistics.

Query Parameters

Parameter	Type	Required	Description
`sort`	string	No	Sort field: `name`, `code`, `total_regulations`, `avg_confidence`, `last_verified`. Default: `name`.
`order`	string	No	Sort order: `asc` or `desc`. Default: `asc`.

Request Example

curl -X GET "https://api.hempdataapi.com/v1/states" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": [
    {
      "code": "AL",
      "name": "Alabama",
      "total_regulations": 18,
      "counts_by_legal_status": {
        "legal": 3,
        "legal_with_restrictions": 8,
        "restricted": 2,
        "prohibited": 4,
        "unclear": 1
      },
      "avg_confidence": 0.82,
      "last_verified": "2026-03-18T04:00:00Z"
    },
    {
      "code": "AK",
      "name": "Alaska",
      "total_regulations": 15,
      "counts_by_legal_status": {
        "legal": 5,
        "legal_with_restrictions": 7,
        "restricted": 1,
        "prohibited": 1,
        "unclear": 1
      },
      "avg_confidence": 0.87,
      "last_verified": "2026-03-18T04:30:00Z"
    },
    {
      "code": "CO",
      "name": "Colorado",
      "total_regulations": 24,
      "counts_by_legal_status": {
        "legal": 8,
        "legal_with_restrictions": 12,
        "restricted": 2,
        "prohibited": 1,
        "unclear": 1
      },
      "avg_confidence": 0.93,
      "last_verified": "2026-03-18T06:00:00Z"
    }
  ],
  "meta": {
    "total": 51,
    "request_id": "req_states_001"
  },
  "errors": []
}

Response Fields

Field	Type	Description
`code`	string	Two-letter state code
`name`	string	Full state name
`total_regulations`	integer	Total number of regulation entries for this state
`counts_by_legal_status`	object	Breakdown of regulations by legal status
`avg_confidence`	number	Average confidence score across all regulations
`last_verified`	string	Most recent verification timestamp for any regulation in this state

GET /v1/states/:code

Get the full regulatory profile for a single state, including all regulation entries and state-level metadata.

Path Parameters

Parameter	Type	Description
`code`	string	Two-letter state code (e.g., `CO`, `CA`, `TX`)

Query Parameters

Parameter	Type	Required	Description
`substance`	string	No	Filter regulations to a specific substance
`product_type`	string	No	Filter regulations to a specific product type
`include_sources`	boolean	No	Include source citations. Default: `false`.
`include_bills`	boolean	No	Include related bills. Default: `false`.

Request Example

curl -X GET "https://api.hempdataapi.com/v1/states/CO?include_sources=true&include_bills=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": {
    "code": "CO",
    "name": "Colorado",
    "region": "West",
    "hemp_program_status": "active",
    "regulatory_authority": "Colorado Department of Agriculture; Marijuana Enforcement Division",
    "hemp_program_url": "https://ag.colorado.gov/plants/hemp",
    "total_regulations": 24,
    "counts_by_legal_status": {
      "legal": 8,
      "legal_with_restrictions": 12,
      "restricted": 2,
      "prohibited": 1,
      "unclear": 1
    },
    "avg_confidence": 0.93,
    "last_verified": "2026-03-18T06:00:00Z",
    "key_highlights": [
      "Mature hemp program with well-defined rules for most cannabinoids",
      "Licensed retail sales of hemp-derived products for adults 21+",
      "Stringent testing and labeling requirements",
      "Active legislation to update THC serving size limits"
    ],
    "regulations": [
      {
        "id": "reg_a1b2c3d4-5678-9012-abcd-ef3456789012",
        "substance": "delta-9-thc",
        "product_type": "edibles",
        "legal_status": "legal_with_restrictions",
        "summary": "Delta-9 THC edibles are legal in Colorado for adults 21+ with licensed retail sale.",
        "confidence": 0.94,
        "last_verified": "2026-03-18T06:00:00Z",
        "sources": [
          {
            "id": "src_001",
            "title": "Colorado Revised Statutes 44-10-601",
            "url": "https://leg.colorado.gov/...",
            "type": "statute",
            "retrieved_at": "2026-03-17T12:00:00Z"
          }
        ],
        "related_bills": [
          {
            "bill_id": "bill_co_2026_hb1234",
            "number": "HB26-1234",
            "title": "Concerning Hemp-Derived Cannabinoid Product Regulation",
            "status": "in_committee"
          }
        ]
      }
    ],
    "pending_bills_count": 3,
    "hr5371_impact_assessment": "Colorado's existing framework is well-positioned for federal rescheduling. Minimal disruption expected."
  },
  "meta": {
    "request_id": "req_states_co_001"
  },
  "errors": []
}

State Profile Fields

Field	Type	Description
`code`	string	Two-letter state code
`name`	string	Full state name
`region`	string	Geographic region (Northeast, Southeast, Midwest, West, Southwest)
`hemp_program_status`	string	`active`, `developing`, `no_program`
`regulatory_authority`	string	Primary regulatory body name(s)
`hemp_program_url`	string or null	URL to the state's hemp program page
`total_regulations`	integer	Total regulation entries
`counts_by_legal_status`	object	Breakdown by legal status
`avg_confidence`	number	Average confidence score
`last_verified`	string	Most recent verification timestamp
`key_highlights`	array	Notable regulatory characteristics
`regulations`	array	Array of regulation objects (same structure as regulations endpoint)
`pending_bills_count`	integer	Number of pending bills related to hemp
`hr5371_impact_assessment`	string	Plain-English assessment of how H.R. 5371 may affect this state