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. A logged-in user can then manage their access tokens using API Access Token Management.

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

  • Using the X-ApiAccessToken request header:
    GET /frads/v1/odata/gcis/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/frads/v1/odata/gcis/Crossings?token=<token-value>

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/frads/v1/odata/gcis/Crossings?$format=xml
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/Crossings?$format=json
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/Crossings?$format=atom
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/Crossings?$format=application/json
    https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/Crossings?$format=application/atom
    
  • Specifying response format via the HTTP request headers:
    GET /frads/v1/odata/gcis/Crossings HTTP/1.1
    Host: safetydata.fra.dot.gov
    Accept: application/atom
    GET /frads/v1/odata/gcis/Crossings HTTP/1.1
    Host: safetydata.fra.dot.gov
    Accept: application/json

Sample Data Requests

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/frads/v1/odata/gcis/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/frads/v1/odata/gcis/Crossings?token=<token-value>
Get crossing data by Railroad
Response is a list of all crossings belonging to a specific Railroad
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/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/frads/v1/odata/gcis/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/frads/v1/odata/gcis/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/frads/v1/odata/gcis/Crossings?$filter=TypeXing eq '2'&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/frads/v1/odata/gcis/Crossings?$filter=TypeXing eq '3'&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/frads/v1/odata/gcis/Crossings?$filter=CrossingId eq '016530M'&token=<token-value>
Get all historical crossing data for a specific crossing
Response is a list of all data marked as historical for a specific crossing location
https://safetydata.fra.dot.gov/MasterWebService/PublicApi/frads/v1/odata/gcis/Crossings?includeHistorical=true&$filter=CrossingId eq '016530M'&token=<token-value>