The Consumer Product Safety Commission Violations & NEISS Data API combines all of the Letters of Advice (LOA) Data and National Electronic Injury Surveillance System (NEISS) Data information into one finalized data set with hospital report information and violation of mandatory standard.
Example Search Urls And Resulting Data
Searching in Violations Record
We require applications using the Violations & NEISS Data API to authenticate all
of their requests by signing up for
an application key on https://api.data.gov/.
This visibility allows us to prevent abusive behavior, and it
also helps us to further understand how categories of applications are
using the API.
We apply this understanding to better meet the needs of developers as
we continue to evolve the platform.
To use the api key, append "api_key=###" to the beginning or the end of
the query.
The following examples will assume that you will append the api key to the query.
The Violations & NEISS Data API returns the reports in either XML or JSON; XML will be returned by default. To return the data in an JSON format, add an Accept header with application.json. Currently, the accept header will only accept: application.xml and application.json. Other requests will return 500 Internal Server Error.
HTTP Status codes will be returned depending on the success or failure of the query. The following status codes will be returned based on the situation:
200: A successful query will respond with a 200 OK response.
204: No Content - Response to a successful request that won't be returning a body.
304: Not Modified - Used when HTTP caching headers are in play.
400 Bad Request - The request is malformed, such as if the body does not parse.
401 Unauthorized - When no or invalid authentication details are provided. Also useful to trigger an auth popup if the API is used from a browser.
403: When an API key has not been input or an incorrect API key has been input, a 401 Unauthorized response will be returned.
404: A query that has no records found will return a 404 Not Found response.
405: Method Not Allowed - When an HTTP method is being requested that isn't allowed for the authenticated user.
410: Gone - Indicates that the resource at this end point is no longer available. Useful as a blanket response for old API versions.
415: Unsupported Media Type - If incorrect content type was provided as part of the request.
422: Unprocessable Entity - Used for validation errors.
429: Too Many Requests - When a request is rejected due to rate limiting.
500: Internal Server Error - A general error occurs when configuration data is invalid.
The Open Data II API performs a case insensitive search for any or all of the parameters using a wildcard search.
Data is returned in XML by default but can also optionally be returned in JSON through the request header:
Violations Record: NEISSRecord:
model
primaryViolation
citation
actionRequested
product
address1
address2
foreignMfg
lotSize
country
cpscCase
psu
weight
stratum
age
sex
race
raceOther
diag
trmtDate
bodyPart
disposition
location
fmv
prodCodes
arr1
narr2
year
The Incident Data API has two parts: Domain and Service.
https://api.cpsc.gov is the domain of the API
https://api.cpsc.gov/opendataApi/loadata is the url for LOA data access. Use this url to filter or search or sort LOA data.
https://api.cpsc.gov/opendataApi/neissdata is the url for NEISS data access. Use this url to filter or search or sort NEISS data.
Querying the above URL will return the first 50 records within the database.
To filter through the data, append the question mark and parameter you want to specify (i.e. https://api.cpsc.gov/opendataApi/neissdata/list?startDate=2010-02-02 ).
You can view the results of the queries below by clicking the links, or entering into a browser URL.
The URL to get all NEISS data in XML format is: https://api.cpsc.gov/opendataApi/neissdata/list
An example of one of the records that result from the resulting data in XML is:
<page xmlns="">
<content>
<content>
<diagOther/>
<cpscCase>1237669</cpscCase>
<psu>21</psu>
<weight>17.321800231933594</weight>
<stratum>V</stratum>
<age>36</age>
<sex>2</sex>
<race>0</race>
<raceOther/>
<diag>
<code>64</code>
<value>" Stain, Sprain"</value>
</diag>
<trmtDate>2000-12-13 00:00:00</trmtDate>
<bodyPart>
<code>92</code>
<value>Finger</value>
</bodyPart>
<disposition>
<code>1</code>
<value>
Treated & Released = Or Examined & released Without Treatment
</value>
</disposition>
<location>
<code>5</code>
<value>other Public Property</value>
</location>
<fmv>0</fmv>
<prod1>
<code>1141</code>
<value>"CONTAINERS, NOT SPECIFIED"</value>
</prod1>
<prod2>
<code>4056</code>
<value>"CABINETS, RACKS, ROOM DIVIDERS AND SHELVES, NEC"</value>
</prod2>
<narr1>
SPRAIN L 5TH FINGER - PT SHOPPING AND BOXES FELL OFF SHELF - WENT
</narr1>
<narr2>TO CATCH THEM AND BENT HER FINGER BACK</narr2>
<year>2000</year>
</content>
</content>
<nextPage>/opendataApi/neissdata/list?page=2</nextPage>
<previosPage/>
<cv>0.07772199619738782</cv>
<last>false</last>
<totalPages>33915</totalPages>
<totalElements>339146</totalElements>
<size>10</size>
<number>0</number>
<first>true</first>
<sort/>
<numberOfElements>10</numberOfElements>
</page>
To get the JSON format, you need to use an API tool to specify that you want to accept an JSON format by adding an Accept header with application.json.
An example of one of the records that result from the resulting data in JSON is:
{"content":[{"diagOther":"","cpscCase":1237669,"psu":21,"weight":17.321800231933594,"stratum":"V","age":36,"sex":2,
"race":0,"raceOther":null,"diag":{"code":64,"value":"\" Stain, Sprain\""},"trmtDate":"2000-12-13 00:00:00","bodyPart":{"code":92,"value":" Finger"},"disposition":{"code":1,
"value":"Treated & Released = Or Examined & released Without Treatment"},"location":{"code":5,"value":"other Public Property"},"fmv":0,"prod1":{"code":1141,"value":"\"CONTAINERS, NOT SPECIFIED\""},
"prod2":{"code":4056,"value":"\"CABINETS, RACKS, ROOM DIVIDERS AND SHELVES, NEC\""},"narr1":"SPRAIN L 5TH FINGER - PT SHOPPING AND BOXES FELL OFF SHELF - WENT",
"narr2":"TO CATCH THEM AND BENT HER FINGER BACK","year":"2000"},
],"nextPage":"/opendataApi/neissdata/list.json?page=2","previosPage":null,"cv":0.07772199619738782,"last":false,"totalPages":33915,"totalElements":339146,"size":10,"number":0,"first":true,"sort":null,"numberOfElements":10}
To increase the response time of the API, the Violations & NEISS Data API divides the data list into pages and returns the first page. Each page contains 50 records of the incident reports. To view the other pages, users will need to append "&page= #" to their query, where # is the page number. Please note that the pages are 0-indexed (0 is the first page, 1 is the second page, and so on).
Pagination information is returned in the header marked as X-Api-Pagination. The information is in a JSON-format with the strings: NextPage, PreviousPages, TotalPages, TotalElements.
NextPage contains the link to the next page of the query. If it is the last page of the query, the value should be null.
PreviousPage contains the link to the previous page of the query. If it is the first page of the query, the value should be null.
TotalPages indicates the total number of pages that contain the records in the query.
TotalElements indicates the total number of elements that were found for the query.
To reduce the amount of requests to the server and to speed up the response time of commonly requested data, output caching has been implemented. Caching is set at 60 seconds.
Searching through the Violations & NEISS Data is very similar to filtering through the data. You can search through the data by appending additional parameters to the URL.
To filter through the data, append the question mark and parameter you want to specify, then append an ampersand along with the parameter you want to search as well (i.e. https://api.cpsc.gov/opendataApi/neissdata/list?startDate=2010-02-02)
This API allows users to query LOA Data from specific dates based on the parameters below:
StartDate
EndData
In addition to querying those specific dates, users can also query a date range. To query a date range, users will use the parameters "startDate" or "endDate". Substitute the Date with one of the parameters above to query a date range.
An example query: https://api.cpsc.gov/opendataApi/loadata/list?startDate=1999-02-02&endData=2002-08-08 Users may also leave the "startDate" parameter out to query from the starting date to the requested date or leave the "endDate" parameter out to query from the requested date to the ending date.
This API allows users to query LOA Data from specific frims based on the parameter below:
firm
An example query: https://api.cpsc.gov/opendataApi/loadata/list?firm=abc The query would search for LOA data related with firm abc.
This API allows users to query Incident Data from specific products based on the parameter below:
product
An example query: https://api.cpsc.gov/opendataApi/loadata/list?product=abc The query would search for LOA data related with product abc.
This API allows users to query NEISS Data from specific dates based on the parameters below:
StartDate
EndData
In addition to querying those specific dates, users can also query a date range. To query a date range, users will use the parameters "startDate" or "endDate". Substitute the Date with one of the parameters above to query a date range.
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?startDate=1999-02-02&endData=2002-08-08 Users may also leave the "startDate" parameter out to query from the starting date to the requested date or leave the "endDate" parameter out to query from the requested date to the ending date.
This API allows users to query NEISS Data from specific gender based on the parameters below:
sex
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?sex=1
The query would search for incidents with all male patients.
This API allows users to query the patients Age within a range, and you must use the parameters
startAge
endAge
Please keep in mind that children below the age of 2 should be recorded in months. Ages recorded as years must be between 2-114. If the patient is older than 115, the age is still recorded as 114 with a note placed in the comments as to the actual age. Ages recorded as months use the convention 200+months, resulting in a record of 201-223.
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?startAge=12&endAge=24
The query would search for incidents with victims that occur from 12- 24 years old.
This API allows users to query the products involved in reported injuries , and you must use the parameters
startProductCode1
endProductCode1
startProductCode2
endProductCode2
startProductCode3
endProductCode3
When only one product is associated with an injury, the product code for that product is recorded as the first product, and the second product is recorded with 4 zeroes (0000). When two products involved in an incident are the same product code, the second product is recorded as 4 zeroes. Please refer to p. 15 of the NEISS Coding Manual
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?startProductCode1=nnnn&endProductCode1=nnnn
The query would search for incidents with product nnnn.
This API allows users to query the final disposition of the patient from the emergency department, and you must use the parameters
disposition
An example query:
https://api.cpsc.gov/opendataApi/neissdata/list?disposition=5
The query would search for incidents that patients are held for observation.
This API allows users to query the body part affected in the product-related incident, and you must use the parameters
bodyPart
If an injury affects more than one body part, the body part that is the most seriously hurt is recorded with other injured body parts noted in the comments.
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?bodyPart=30
The query would search for incidents that patients are hurt in shoulder.
This API allows users to queryt the nature of the injury, and you must use the parameters
diagnosis
When more than one diagnosis is evident in the patient, only the most severe is recorded. Other diagnoses are noted in the comments.
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?diagnosis=50
The query would search for incidents that patients are diagnosed as Amputation.
This API allows users to query the location where the incident occurred, and you must use the parameters
location
An example query: https://api.cpsc.gov/opendataApi/neissdata/list?location=1
The query would search for incidents that occur at home.