Quick Start Guide

FRA has selected Open Data (OData) as the API protocol to be used to retrieve FRA data. OData uses the Representational state transfer (REST) model for all data requests. Although the OData protocol supports a full suite of Create, Update, and Delete (CRUD) functionality, FRA supports only commands associated with retrieving data.

The following sites provide numerous examples and additional information for the use of OData:

API Access Tokens

All data requests, including the examples on this page, must include an FRA-supplied API access token that has been assigned to an authorized user. To get an access token you will need to Request Access to register for a user account.

The API access token can be included in the HTTP request in either of two ways:

  • Using the X-ApiAccessToken request header: 
    GET /GCIS/v1/odata/Crossings HTTP/1.1
Host: safetydata.fra.dot.gov
X-ApiAccessToken: <token-value>
  • Using the token URI query string parameter: 
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?token=<token-value>

Requesting MetaData

One key component of the OData protocol is its support for exposure of the full metadata of the datasource. It is possible to see the full structure of the data including data types, relationships, and other associated data.

The OData API exposes a metadata document that describes the resources available for use in further REST operations. You can request the metadata document using the following URI: 

https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/$metadata

Response Formats

Users also have the option to receive response data in JSON or XML-based Atom format. Although the default for the FRA is XML, the user can specify the desired format in the request via either the $format query string parameter or the standard Accept HTTP header.

The format can be specified as one of the well-known MIME content type such as application/json for JSON or text/xml for XML. As a short form, you may alternately use json, xml, or atom.

  • Specifying response format via the query string: 
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$format=xml
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$format=json
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$format=atom
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$format=application/json
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$format=application/atom
  • Specifying response format via the HTTP request headers: 
    GET /GCIS/v1/odata/Crossings HTTP/1.1
Host: safetydata.fra.dot.gov
Accept: application/atom
    GET /GCIS/v1/odata/Crossings HTTP/1.1
Host: safetydata.fra.dot.gov
Accept: application/json

Sample Data Requests

Please note that only 10 crossings are available per one API Request.

To access data, insert your assigned token into the request for query results to be returned. If you do not have a token you will need to Request Access to register for an account and be assigned a token.

The following are sample requests to retrieve Crossing data using OData query expressions:

Get latest crossing data for a specific crossing
Response is a list of data last submitted for a specific crossing location 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=CrossingId eq '016530M'&token=<token-value>
Get all crossing data
Response is a list of all crossings and their supporting data 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?token=<token-value>
Get Crossings (other than the first 10)
Crossings will be displayed 10 at a time. Do the following (&$skip=##) to see additional crossings.

This will give you Crossings 11 to 20 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?token=<token-value>&$skip=10
This will give you Crossings 21 to 30 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?token=<token-value>&$skip=20
You can increase the "&$skip=" to see all the crossings.
Get crossing data by Railroad
Response is a list of all crossings belonging to a specific Railroad 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=OperatingRailroadCode eq 'BN'&token=<token-value>
Get crossing data by State
Response is a list of all crossings belonging to a specific State 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=StateCD eq '30'&token=<token-value>
Get crossing data by Agency
Response is a list of all crossings belonging to a specific Agency 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=ReportingAgencyId eq 171&token=<token-value>
Get all public crossing data
Response is a list of all public crossings and their supporting data 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=TypeXing eq '3'&token=<token-value>
Get all private crossing data
Response is a list of all private crossings and their supporting data 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=TypeXing eq '2'&token=<token-value>
Get all crossing data for a specific crossing
Response is a list of all data for a specific crossing location 
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/GCIS/v1/odata/Crossings?$filter=CrossingId eq '016530M'&token=<token-value>
Get all historical crossing data for a specific crossing
Attention: Currently historical records are not available for public users via API. Please use the following link to get historical crossing records in Excel format: 
http://safetydata.fra.dot.gov/OfficeofSafety/publicsite/DownloadCrossingInventoryData.aspx