Accessing the API Using HTTP Requests

API Versions

API.dol.gov (V1)

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

GEThttp://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

Data.dol.gov (V2)

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.<

Note: Each API key is limited to 250 queries per hour.

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.

Note: The offset works differently for these datasets. You need to use the columns name with the offset amount such as "column name/offset number", An example would be - "/flc_name/25".



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.

:

 The delimiter separating columns

/columns/first_column:second_column:third_column

Example.

Dates (yyyy-mm-dd)

Searching by dates
Key/Value Description

date_column

 Search dates (start_date and / or end_date ) you want to see must be included. A maximum of 200 rows will be returned in reverse order from the end date or current date.
(Column Name) Please specify the date column name to search by-date

start_date

 Start date (start_date) will search from the start date to current date (today).

end_date

 End date will be the last date in the search.
Both start_date and end_date Exact date range incldues the start_date and end_date.

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

 Example start date parameter.

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

 Example end date parameter.

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

 Example date range which includes both start_date and end_date.

Filter Column

The "Filter Column" can be selected individually with the columns keyword or matching keywords. For example, the user is searching by city for "Edmonton". The search will show you all matching items for that city. NOTE: You can have multiple column searches by using ":" the between columns. The search results will be sorted by the first "filter_column" field in ascending order. See examples below for formatting.
Segment Description

filter_column

 Must be included for filter column filtering.

=

 The equal sign "=" must be included after the selected field for the filter column and before the fields value you are looking to find. Example URL

curl -k -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/SweatToilAllCountries/limit/130/filter_column/region=asia

:

 The delimiter separating filter column name

/filter_column/first_columnname=value:second_columnname=value:third_columnname=value

 Example URL

curl -k -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/accident/limit/130/filter_column/event_keyword=crushed:report_id=04547


Multi-Filtering

Examples
Example URL Explanation

curl -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/accident/format/xml/limit/10/offset/5/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 ascending order by the summary_nr column.

curl -k -H "X-API-KEY: YOUR_API_KEY" https://data.dol.gov/get/accident/limit/130/filter_column/event_keyword=crushed:report_id=04547

 Select 130 rows from the OSHA accident table. Result is in JSON format, will include the 2 specified filter_column (event_keyword & report_id) and will be sorted in ascending order by the filter_column. Only returns matching & exact search results falls within event_keyword & report_id.