NY APIpuc.ny.gov ↗
Search and retrieve regulatory filings, case metadata, and documents from the New York Public Service Commission DMM system via 3 structured endpoints.
What is the NY API?
The puc.ny.gov API exposes 3 endpoints for accessing the New York Public Service Commission's Document Matter Management system. Use search_documents to run full-text queries across the DPS document archive, get_case_details to retrieve case metadata and the internal matter_seq identifier, and get_case_documents to pull all public filings for a given case — including document type, filing date, file size, and direct download URLs.
curl -X GET 'https://api.parse.bot/scraper/3049f238-c58c-42d9-a436-623487309d55/search_documents?page=1&query=testimony' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace puc-ny-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.new_york_public_service_commission_dps_dmm_api import DPS, Document, Case, CaseMetadata, CaseDocument, CaseNotFound
dps = DPS()
# Search for documents related to "rate case"
for doc in dps.documents.search(query="rate case", limit=5):
print(doc.title, doc.document_id, doc.download_url)
# Fetch case details by case number
case = dps.cases.get(case_number="07-E-0949")
print(case.case_number, case.matter_seq)
print(case.metadata.industry, case.metadata.matter_type)
# Get all documents filed in the case
for filing in case.documents(limit=10):
print(filing.title, filing.date_filed, filing.document_type, filing.file_size)
Full-text search over the DPS document archive. Returns paginated results with document titles, snippets, and download links. Each page contains up to ~20 results. The query matches across all document text; results are relevance-ranked.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based) |
| query | string | Search keyword or phrase |
{
"type": "object",
"fields": {
"page": "integer — current page number",
"query": "string — the search query used",
"results": "array of document objects with title, document_id, download_url, snippet, and page",
"total_results": "string — total results text from the page header"
},
"sample": {
"data": {
"page": 1,
"query": "testimony",
"results": [
{
"page": 1,
"title": "Response to 6/21/04 order",
"snippet": "March 29,2006 VIA FEDERAL EXPRESS...",
"document_id": "{051312D4-3DC0-400A-98BE-BA13FF2A7B91}",
"download_url": "https://documents.dps.ny.gov/search/Home/DownloadDoc/Find?id=%7B051312D4-3DC0-400A-98BE-BA13FF2A7B91%7D&ext=pdf&docTitle=Response%20to%206%2F21%2F04%20order"
}
],
"total_results": ""
},
"status": "success"
}
}About the NY API
Document Search
The search_documents endpoint accepts a query string and optional page integer (1-based) and returns paginated results of up to roughly 20 documents per page. Each result object includes a title, document_id, download_url, snippet of matching text, and the page number. The total_results field surfaces the count string as displayed in the archive's page header, so you can calculate how many pages to iterate.
Case Lookup and Metadata
The get_case_details endpoint takes a case_number in the format NN-X-NNNN (e.g., 07-E-0949) and returns a metadata object with fields such as matter_number, industry, matter_type, company, status, and title when available. Critically, it also returns a matter_seq — the internal numeric identifier required to call get_case_documents. If you already know the matter_seq, you can bypass this step.
Case Document Retrieval
The get_case_documents endpoint accepts either a case_number or a matter_seq directly. It returns a documents array and a total_documents count. Each document object includes item_no, date_filed, document_type, title, file_name, file_size, doc_ref_id, and a download_url pointing to the actual filing. This covers all publicly accessible documents on record for the case — useful for pulling complete filing histories from rate cases, certificate proceedings, and complaint dockets.
Coverage and Format
This API covers proceedings before the New York Public Service Commission as indexed in the DPS DMM system. Case numbers follow the NN-X-NNNN convention used by NYPSC dockets. Document types vary by case and may include petitions, orders, comments, testimony, and staff reports. The download URLs resolve to the actual filed documents hosted by the NYPSC.
The NY API is a managed, monitored endpoint for puc.ny.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when puc.ny.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official puc.ny.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor all new filings in a specific PSC case by polling
get_case_documentsand trackingdate_filedvalues. - Build a research index of NYPSC regulatory documents by paginating
search_documentsacross topic keywords like 'rate increase' or 'interconnection'. - Retrieve
companyandmatter_typemetadata fromget_case_detailsto classify cases by industry sector and proceeding type. - Automate download of all documents in a contested rate case using the
download_urlfields returned byget_case_documents. - Cross-reference
matter_seqvalues fromget_case_detailswith external datasets to map utility proceedings to geographic service territories. - Track regulatory status changes for energy or telecom companies by querying
get_case_detailsfor thestatusfield across multiple case numbers. - Full-text search the DPS archive with
search_documentsto find all proceedings referencing a specific utility, technology, or policy term.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does the New York Public Service Commission provide an official developer API?+
What does `get_case_details` return and when is `matter_seq` needed?+
get_case_details returns a metadata object with fields including matter_number, industry, matter_type, company, status, and title. It also returns the matter_seq — a numeric string that is the required input for get_case_documents when you don't already have it. If you do have the matter_seq (e.g., from a prior lookup), you can pass it directly to get_case_documents and skip calling get_case_details.How does pagination work in `search_documents`?+
page parameter is 1-based. The response includes a total_results string taken from the archive's page header — note this is a string, not a guaranteed integer, so parse it before using it in arithmetic. Iterate the page parameter to retrieve subsequent result sets.Does the API expose hearing schedules, calendar events, or PSC commissioner information?+
Are documents from all NYPSC industries and matter types available?+
documents array only reflects publicly available records. Cases with no public documents will return an empty array.