NYS Laws API¶
In order to utilize the Laws API we’ll go over some quick terminology:
- Law Id
A three letter code that identifies the law, e.g. EDN for Education Law.
- Document Id
A string that identifies a particular document within a body of law. Contains the three letter law id so it can uniquely identify a document.
- Location Id
This is simply the document id without the three letter law id prefix.
- Published Date
Since the nature of laws are fairly temporal we keep track of changes to the laws using the published date. It’s possible to retrieve law documents roughly as they were represented during any week since October 2014.
Get a list of law ids¶
Usage
(GET) /api/3/laws
Optional Params
Parameter |
Values |
Description |
|---|---|---|
limit |
1 - 1000 |
Number of results to return |
offset |
>= 1 |
Result number to start from |
Response
{
"success": true,
"message": "Listing of consolidated and unconsolidated NYS Laws",
"responseType": "law-info list",
"total": 134,
"offsetStart": 1,
"offsetEnd": 134,
"limit": 0,
"result": {
"items": [
{
"lawId": "ABC",
"name": "Alcoholic Beverage Control",
"lawType": "CONSOLIDATED",
"chapter": "3-B"
},
{
"lawId": "ABP",
"name": "Abandoned Property",
"lawType": "CONSOLIDATED",
"chapter": "1"
},
(truncated)
The lawId in the response is the three letter id for the law.
Get the law structure¶
Laws are represented as a collection of sub documents, each of which is structured within a hierarchy. The following call will provide the structure of the law.
Usage
(GET) /api/3/laws/{lawId}
Optional Params
Parameter |
Values |
Description |
|---|---|---|
date |
ISO date |
Fetch law structure as it appeared prior to or on this date. |
full |
boolean |
If set to true, all the law text will also be returned. |
Examples
/api/3/laws/ABC // Get latest law structure for ABC law
/api/3/laws/TAX?date=2015-01-01 // Get law structure for TAX law as it appeared on or before 01/01/2015
/api/3/laws/EDN?full=true // Get latest law structure for EDN law as well as the text body of the law
Response
// /api/3/laws/RPT
{
"success": true,
"message": "The document structure for RPT law",
"responseType": "law-tree",
"result": {
"lawVersion": {
"lawId": "RPT", // Three letter law id
"activeDate": "2015-01-02" // Date on which this law content was up to date
},
"info": {
"lawId": "RPT",
"name": "Real Property Tax", // Name of the law
"lawType": "CONSOLIDATED", // One of CONSOLIDATED, UNCONSOLIDATED, COURT_ACTS, RULES, MISC
"chapter": "50-A" // Chapter of law
},
"documents": { // This is a repeating document structure
"lawId": "RPT",
"locationId": "-CH50-A", // The location id identifes this sub document within this law
"title": "Real Property Tax", // Title of this sub document if available.
"docType": "CHAPTER",
"docLevelId": "50-A", // The doc level id identifies the sub document within the current
// level in the hierarchy. For example if 'docType' is ARTICLE
// and docLevelId is 1, it means this is Article 1.
"activeDate": "2014-09-22", // Date this particular document was updated
"sequenceNo": 1, // Preserves ordering of sub documents
"repealedDate": null, // Date this document was repealed (if applicable)
"repealed": false, // This will be true if the document was repealed,
// 'repealedDate' will be set with the date.
"text": null, // Text of this document (only set when ?full=true)
"documents": { // Contains the sub documents of this document
"items": [ // It's a recursive structure
{
"lawId": "RPT",
"locationId": "A1",
"title": "SHORT TITLE; DEFINITIONS",
"docType": "ARTICLE",
"docLevelId": "1",
"activeDate": "2014-09-22",
"sequenceNo": 2,
"repealedDate": null,
"text": null,
"documents": {
"items": [
{
"lawId": "RPT",
"locationId": "100",
"title": "Short title",
"docType": "SECTION",
"docLevelId": "100",
"activeDate": "2014-09-22",
"sequenceNo": 3,
"repealedDate": null,
"text": null,
"documents": { // Note there are no sub documents for this doc
"items": [],
"size": 0
},
"repealed": false
},
(truncated)
When the request parameter full is set to true the ‘text’ fields within all the sub-documents will contain the text body. Note that response can be rather large (several MB) for certain laws so keep that in mind.
If you want to retrieve a specific law document use the following API call:
Get a law sub document¶
Usage
(GET) /api/3/laws/{lawId}/{locationId}
The lawId once again is the three letter code (e.g. EDN, TAX) and locationId is the identifier for the sub document. You can discover the locationId when you make an API request for the law structure (see above section). See the ‘locationId’ field for that response.
Examples
/api/3/laws/TAX/8/ // Get section 8 of Tax law
/api/3/laws/EDN/A2/ // Get article 2 of Education law
Note
A trailing slash is important for this API call because the locationId may have periods which would otherwise be interpreted as an extension of sorts. When in doubt, try adding the trailing slash.
Response
The response here is straight-forward.
{
"success" : true,
"message" : "Law document for location A2 in EDN law ",
"responseType" : "law-doc-info-detail",
"result" : {
"lawId" : "EDN",
"lawName" : "Education",
"locationId" : "A2",
"title" : "Dignity For All Students",
"docType" : "ARTICLE",
"docLevelId" : "2",
"activeDate" : "2019-05-03",
"text" : "ARTICLE 2 (text truncated for brevity)" // The text body of the law will be here,
"parentLocationIds" : [ "-CH16", "T1" ],
"parents" : [ {
"lawId" : "EDN",
"lawName" : "Education",
"locationId" : "-CH16",
"title" : "Education",
"docType" : "CHAPTER",
"docLevelId" : "16",
"activeDate" : "2019-11-01"
}, {
"lawId" : "EDN",
"lawName" : "Education",
"locationId" : "T1",
"title" : "General Provisions Article 1 Short Title and Definitions (§§",
"docType" : "TITLE",
"docLevelId" : "1",
"activeDate" : "2019-04-19"
} ],
"prevSibling" : {
"lawId" : "EDN",
"lawName" : "Education",
"locationId" : "A1",
"title" : "Short Title and Definitions",
"docType" : "ARTICLE",
"docLevelId" : "1",
"activeDate" : "2014-09-22"
},
"nextSibling" : {
"lawId" : "EDN",
"lawName" : "Education",
"locationId" : "A3",
"title" : "Education Department",
"docType" : "ARTICLE",
"docLevelId" : "3",
"activeDate" : "2014-09-22"
}
}
}
If the law document was not found you will receive an error response
{
"success": false,
"message": "The requested law document was not found",
"responseType": "error",
"errorCode": 21,
"errorData": {
"lawDocId": "EDNA22",
"endDate": "2015-01-09"
},
"errorDataType": "law-doc-query"
}
Search for law documents¶
Usage
(GET) /api/3/laws/search?term= // Search across all law volumes
(GET) /api/3/laws/{lawId}/search?term= // Search within a specific law volume
Required Params
Parameter |
Values |
Description |
|---|---|---|
term |
string |
The full text search term. |
Optional Params
Parameter |
Values |
Description |
|---|---|---|
sort |
string |
Sort using any field from the result object, e.g. lawId:ASC |
limit |
1 - 1000 |
Number of results to return (high limits take longer) |
offset |
>= 1 |
Result number to start from |
Examples
/api/3/laws/search?term=chickens // Search all law volumes for the word 'chickens'
Get law document updates¶
To identify which documents have been modified or added to a body of law, use the law updates API.
To detect updates to the structure of the law document tree, see Get law tree updates.
Note
Law updates are received in a batch update on a weekly basis, so updates that occur during the week will only be visible at the end of that week.
Usage
List of laws updated during the given date/time range
/api/3/laws/updates/{fromDateTime}/{toDateTime}
Note
The fromDateTime and toDateTime should be formatted as the ISO Date Time format. For example December 10, 2014, 1:30:02 PM should be inputted as 2014-12-10T13:30:02. The fromDateTime and toDateTime range is exclusive.
All updates made on a specific body of law
/api/3/laws/{lawId}/updates/
e.g. /api/3/laws/ABC/updates/
/api/3/laws/VAT/updates/
All updates made on a specific body of law during a date/time range
/api/3/laws/{lawId}/updates/{fromDateTime}/{toDateTime}
Optional Params
Parameter |
Values |
Description |
|---|---|---|
type |
(processed|published) |
The type of law update |
detail |
boolean |
Set to true for updates to individual law documents. |
order |
string (asc|desc) |
Order the results by update date/time |
limit |
1 - 1000 |
Number of results to return (high limits take longer) |
offset |
>= 1 |
Result number to start from |
Response
Global law updates
e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00?type=published
{
success: true,
message: "",
responseType: "update-token list",
total: 33,
offsetStart: 1,
offsetEnd: 33,
limit: 50,
result: {
items: [
{
id: {
lawId: "RSS", // Which body of law was updated
activeDate: "2015-08-07" // The active published date
},
contentType: "LAW",
sourceId: "20150807.UPDATE",
sourceDateTime: "2015-08-07T00:00", // Date of the source data
processedDateTime: "2015-09-10T15:00:14.551822" // Date we processed this update
}, (truncated..)
Detailed law doc updates
e.g. /api/3/laws/updates/2015-09-01T00:00:00/2015-10-01T00:00:00?detail=true&type=published
/api/3/laws/ABC/updates/
{
success: true,
message: "",
responseType: "update-digest list",
total: 431,
offsetStart: 1,
offsetEnd: 50,
limit: 50,
result: {
items: [
{
id: {
lawId: "ABC",
locationId: "120", // Location id of doc that was updated
publishedDate: "2014-09-22" // Published date of this doc
},
contentType: "LAW",
sourceId: "DATABASE.LAW3",
sourceDateTime: "2014-09-22T00:00",
processedDateTime: "2015-06-04T14:36:01.426676",
action: "Insert",
scope: "Law Document",
fields: { },
fieldCount: 0
},
Get law tree updates¶
Gets a list of laws which have had structural changes over a specified date/time range.
To see updates to the content of law documents, see Get law document updates.
Usage
List of laws with tree updates during the given date/time range
/api/3/laws/tree/updates
/api/3/laws/tree/updates/{fromDateTime}?type=published
/api/3/laws/tree/updates/{fromDateTime}/{toDateTime}?type=published
The fromDateTime and toDateTime should be formatted as the ISO Date Time format. For example December 10, 2014, 1:30:02 PM should be inputted as 2014-12-10T13:30:02. The fromDateTime and toDateTime range is exclusive. If excluded, fromDateTime defaults to Jan 1 1970 and toDateTime defaults to the current datetime
Optional Params
Parameter |
Values |
Description |
|---|---|---|
type |
(processed|published) |
The type of law update |
order |
string (asc|desc) |
Order the results by update date/time |
limit |
1 - 1000 |
Number of results to return (high limits take longer) |
offset |
>= 1 |
Result number to start from |
Response
Get law tree updates by published date
e.g. /api/3/laws/tree/updates/2016-10-06/2016-10-08?type=published
{
success: true,
message: "",
responseType: "update-token list",
total: 23,
offsetStart: 1,
offsetEnd: 23,
limit: 50,
result: {
items: [
{
id: {
lawId: "PAR", // Location id of doc that was updated
activeDate: "2016-10-07" // Published date of this doc
},
contentType: "LAW",
sourceId: "20161007.UPDATE",
sourceDateTime: "2016-10-07T00:00",
processedDateTime: "2017-08-15T12:40:02.271155"
},
(truncated)
Get repealed laws¶
Gets a list of law documents that have been repealed with the option of restricting to a specified date/time range. The date/time range applies to the processed date of the law document, not the official repeal date.
Usage
List of laws repealed during the given date/time range
/api/3/laws/repealed
Optional Params
Parameter |
Values |
Description |
|---|---|---|
fromDateTime |
ISO 8601 datetime |
default 1970-01-01 - The inclusive start time of the specified time range |
toDateTime |
ISO 8601 datetime |
default now - The inclusive end time of the specified time period |
Get a law pdf¶
Usage
Retrieve law pdf by document id. Inputting only the law ID will get you the root node for that chapter.
(GET) /pdf/laws/{docId}
Optional Params
Parameter |
Values |
Description |
|---|---|---|
full |
(true|false) |
Whether to get all the children of this document. |
Examples
Request law document CC0A1 and its children
/api/3/laws/CCOA1?full=true