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 examplese 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 /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?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/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+xml
    
  • Specifying response format via the HTTP request headers:
    GET /odata/Crossings HTTP/1.1
    Host: safetydata.fra.dot.gov
    Accept: application/atom+xml
    GET /odata/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: