Accessing the APIs Using HTTP Requests

Authentication

This method does not require authentication. An API key is not required.

Arguments

$metadata (required)

Example URL

Read the metadata for the FORMS dataset

http://api.dol.gov/V1/FORMS/$metadata

HTTP Error Codes

Requesting Dataset Metadata - HTTP Error Codes
Error Code Error Text Comments
404 Resource not found The dataset name or table name is invalid

Comments

None

Authentication

This method does not require authentication.

Arguments

None

Example URL

Read Agencies table from the FORMS dataset

http://api.dol.gov/V1/FORMS/Agencies

HTTP Error Codes

Reading a Table - HTTP Error Codes
Error Code Error Text Comments
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

This method does not require authentication.

Arguments

$top (required)

Example URL

Read the first 10 records of the Agencies table from the FORMS dataset

http://api.dol.gov/V1/FORMS/Agencies?$top=10

HTTP Error Codes

Limit the Number of Results Returned - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

This method does not require authentication

Arguments

$skip (required)

Example URL

Read the Agencies table from the FORMS dataset, skipping the first 5 results

http://api.dol.gov/V1/FORMS/Agencies?$skip=5

HTTP Error Codes

Skip a Number of Results - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

This method does not require authentication

Arguments

$top (required)

$skip (required)

Example URL

Read records 21-30 from the Agencies table in FORMS dataset

http://api.dol.gov/V1/FORMS/Agencies?$skip=20&$top=10

HTTP Error Codes

Data Pagination by Combining Top and Skip - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

This method does not require authentication

Arguments

$select

Example URL

Read records from the AgencyForms table in FORMS dataset, returning only the FormNumber and Title columns.

http://api.dol.gov/V1/FORMS/AgencyForms?$select=FormNumber,Title

HTTP Error Codes

Selecting Specific Columns - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

This method does not require authentication

Arguments

$orderby

Example URLs

Read records from the AgencyForms table in FORMS dataset, sorting by the FormNumber column.

http://api.dol.gov/V1/FORMS/AgencyForms?$orderby=FormNumber

To sort the column by desc order, add desc after the column name

http://api.dol.gov/V1/FORMS/AgencyForms?$orderby=FormNumber desc

HTTP Error Codes

Sorting Data - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

  • Ascending is the default order.
  • A maximum of 100 records will be returned
  • More than one column can be specified. Separate column names with commas.

Authentication

This method does not require authentication

Arguments

$filter

Comparison Keywords

  • eq – Equal to
  • ne – Not Equal to
  • gt – Greater than
  • lt – Less than
  • ge – Greater than or equal to
  • le – Less than or equal to

Example URL

Read records from the AgencyForms table in FORMS dataset, returning only the records where the AgencyId is equal to 'MSHA'.

http://api.dol.gov/V1/FORMS/AgencyForms?$filter=AgencyId eq 'MSHA'

Example Response

[response]

HTTP Error Codes

Filtering Data - Single Filter - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Authentication

</p>This method does not require authentication</p>

Arguments

  • $filter (required)
  • and
  • or

Comparison Keywords

  • eq – Equal to
  • ne – Not Equal to
  • gt – Greater than
  • lt – Less than
  • ge – Greater than or equal to
  • le – Less than or equal to

Example URL

Read records from the AgencyForms table in FORMS dataset where the AgencyId is equal to MSHA and the Title is equal to 'Legal Identity Report'.

http://api.dol.gov/V1/FORMS/AgencyForms?$filter=(AgencyId eq 'MSHA') and (Title eq 'Legal
                    Identity Report')

HTTP Error Codes

Filtering Data - Multiple Filters - HTTP Error Codes
Error Code Error Text Comments
400 Bad Request The query contains an error. Read returned value for specific error.
404 Resource not found The dataset name or table name is invalid

Comments

A maximum of 100 records will be returned

Use Your Quarry API Key (Required)

If you have an APIv1 Key, you may also use it for Quarry/APIV2

Register at https://devtools.dol.gov/developer/Account/Register to get a QUARRY API key. The new API key will be emailed to you.

Curl Generic Quarry Usage (Strict Order)

curl -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/ALIAS/filtername1/filtervalue1/filtername2/filtervalue2


Item Description
YOUR_API_KEY Your QUARRY API key
ALIAS A valid alias data table name
filtername A filter name that is part of a key/value pair
filtervalue The value of the filter key/pair that can either set a fixed parameter or is a number

Filtering Options

Format

Dataset will be in JSON or XML.
Key/Value Description

/format/json

JSON

/format/xml

XML
Default JSON

Limit

Number of rows to return. While the maximum allowed for APIv2 is 200, a value of 0 will return the limit set by the server which could differ.
Key/Value Description

/limit/0

Return all allowable data.

/limit/YOUR_NUMBER

Return desired number of rows.

/limit/200

Quarry API return limit.
Default Return all allowable data.

Offset

Offset allows you to paginate a request and by using offset, you will be able to browse data in sets of up to 200 records at a time. Increasing the offset each time you request records will allow you to see additional records from the dataset you are viewing.
Key/Value Description

/offset/YOUR_NUMBER

Paginate the request starting at YOUR_NUMBER.

Order

Ascending or descending sorting order as determined by the targeted datasource
Key/Value Description

/orderby/asc

Ascending order.

/orderby/desc

Descending order.
Default Ascending order.

Columns

Columns can be selected individually with the columns keyword. Datasets will be sorted by the first column field.
Segment Description

columns

Must be included for column filtering.

[

Begin columns option

:

The delimiter separating columns

]

End column selection

/columns/[first_column:second_column:third_column]

Example.

Dates (yyyy-mm-dd)

Searching by dates
Key/Value Description

date_column

Must be included to search dates.
(Column Name) Specify the column name to search by-date

start_date

Start date will search from the start date to now.

end_date

The past up to the end date (200 maximum rows returned in reversed order from the end date)
Both start_date and end_date Exact date range.

/date_column/COLUMN_NAME/start_date/YYYY-MM-DD

Example (by start date)

/date_column/COLUMN_NAME/end_date/YYYY-MM-DD

Example (by end date)

/date_column/COLUMN_NAME/start_date/YYYY-MM-DD/end_date/YYYY-MM-DD

Example (by date range)

Multi-Filtering

Examples
Example URL Explanation

curl -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/accident/format/xml/limit/10/orderby/desc/columns/[summary_nr:event_desc:event_time]

Select 10 rows from the OSHA accident table. Result is in XML format, will include the 3 specified columns (summary_nr,event_desc,event_time) and will be sorted in descending order by the summary_nr column.

curl -k -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/violation/limit/130/orderby/asc/columns/[issuance_date:citation_id:standard]/date_column/issuance_date/start_date/2010-03-15/end_date/2015-04-15

Select 130 rows from the OSHA Violation table. Result is in JSON format, will include the 3 specified columns (issuance_date,citation_id,standard) and will be sorted in ascending order by the issuance_date column. Only returns results where issuance_date falls within the specified date range (2010-03-15 to 2015-04-15)