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 Authorization

All data requests, including the examples on this page, must include a securely approved GCIS user account and an FRA-supplied API access token that has been assigned for each authorized session. To get an GCIS user account, you will need to register at the secure Grade Crossing Inventory System (GCIS). Authenticated users will be provided authorization to GET and POST GCIS data.
The Authorization can be included in the HTTPS request using Base64Encoded string:
  • Using the Authorization request header:
    GET https://safetydata.fra.dot.gov/MasterWebService/SecureAPI/api/Authenticate HTTP/1.1
    Host: stage.fra.dot.gov
    Authorization: Basic Base64Encoding(username:password) 
                    
  • Using query string
    GET https://safetydata.fra.dot.gov/MasterWebService/SecureAPI/api/Authenticate?username=user&password=pass
                    
  • If successful, an Access Token object will be returned:
                    
    Token:af63163c-a581-49da-a8e4-21321e099c02
    UserName:user@user.com
    IssueTime:2014-04-22T14:06:48.4545975-04:00
    ExpireTime:2014-04-22T14:36:48.4545975-04:00
    HasExpired:false
                    
    All subsequent calls to the API must contain the API Access Token as part of the request, otherwise, a Request did not include an authorized access token will be returned.
  • If unsuccessful, an error message will be returned.

API Access Tokens

Once successfully logged in using your securely approved GCIS user account, you will be assigned an API Access Token for the current session. To get an access token you will need to Sign In using your securely approved GCIS user account. A logged-in user can then view their access tokens on the Data Sampler page.

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

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

Note:
Tokens remain valid for 20 minutes from the moment they are generated.
A new token will not be generated until the existing token has expired.

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

Paging

Paging is an integral part of the querying logic, as such only limited number of results can be requested at a time. To page, use the $top and $skip parameters.

Get all Published crossing data 1000 pages at a time
page 1
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$top=1000&$filter=ReportStatus eq 'Published'&token=<token-value>
page 2
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$top=1000&$skip=1000&$filter=ReportStatus eq 'Published'&token=<token-value>
....
page 5
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$top=1000&$skip=4000&$filter=ReportStatus eq 'Published'&token=<token-value>

Sample Data GET Requests

Note:
When you submit a Get request with filters, please make sure there are no single quotes (‘) for the fields that are marked as decimal or double.
To get value types for all fields please request the metadata document using the URL from the 'Requesting MetaData' section on this page.

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 Sign In to retrieve your assigned 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://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=CrossingId eq '016530M'&token=<token-value>
Get current and all historical crossing data for a specific crossing
Response is a list of all data marked as historical for a specific crossing location along with the active record
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=(CrossingId eq '028899F' and (ReportStatus eq 'Published' or ReportStatus eq 'Expired'))&token=<token-value>
Get historical crossing data for a specific crossing
Response is a list of all data marked as historical for a specific crossing location
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=(CrossingId eq '028899F' and ReportStatus eq 'Expired')&token=<token-value>
Get all Published crossing data
Response is a list of all crossings and their supporting data
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=ReportStatus eq 'Published'&token=<token-value>
Get all pending crossing data for your agency
Response is a list of data last submitted for a specific crossing location
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=ReportStatus eq 'Pending'&token=<token-value>
Get all Published & Expired crossing data by CrossingID
Response is a list of all crossings and their supporting data
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings('151004T')?token=<token-value>
Get all crossing data with errors for your agency
Response is a list of crossings that has not passed validation after a submission was done
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=HasErrors eq 'True'&token=<token-value>
Get crossing submission validation errors
Response is a list of crossings that has not passed validation after a submission was done
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/CrossingErrors?$filter=CrossingId+eq+'350152L'&token=<token-value>
Get all crossing data with Submission Id
Response is a list of data last submitted for a specific crossing location
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=SubmissionId eq '516EA755-2EF1-476A-BFEE-02DA57B05A46'&token=<token-value>
Get crossing data by Railroad
Response is a list of all crossings belonging to a specific Railroad
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=Railroad eq 'BN'&token=<token-value>
Get crossing data by State
Response is a list of all crossings belonging to a specific State
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=StateCD eq 30&token=<token-value>
Get all public crossing data
Response is a list of all public crossings and their supporting data
https://stage.fra.dot.gov/MasterWebService/SecureAPI/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://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?$filter=TypeXing eq '2'&token=<token-value>
Get all lookups
Response is a list of lookup values. The lookup ID’s are used to make updates to crossing values
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Lookups?token=<token-value>
Get all Locations
Response is a list of lookup values. The values are used to make updates to the location part crossing values
https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Locations?token=<token-value>

Sample Data Submissions using POST, PATCH or PUT Requests

Note:
When you submit a Post, PATCH or PUT requests, please use a single quoutes for the fields that are marked as decimal.
To get value types for all fields please request the metadata document using the URL from the 'Requesting MetaData' section on this page.
Result
When submitting a crossing data that is not formatted properly, a 200 or 400 result type can be expected. Receiving a 400 bad request may be due to sending an invalid request.
e.g. Empty body or failure due to validation errors
    HTTP/1.1 200 OK
    {"SubmissionID":"6bfecdec-6a78-4c19-a760-4cb2002d9cfa","Message":"Success","HasError":false,"Processed":true, "Comments":""}
    HTTP/1.1 400 Bad Request
    {"SubmissionID":"6bfecdec-6a78-4c19-a760-4cb2002d9cfa","Message":"The submission was processed with validation errors","HasError":true,"Processed":true, "Comments":"Pending record has been created"}
Send single Crossing Data for Processing
A single crossing can be sent using POST, PATCH or PUT endpoints.
Note:
These submissions will not require the generation of a new token per each HTTP request if they all fall within the same 20 minute span.
The following POST request will mark the crossing as closed.
POST https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?token=<token-value>
Content-type: application/json
{
	"Crossings":
    [
        {
           "CrossingId": "857733N",
           "ReasonId":16,
           "ReportType":"Full Inventory Record ",
           "Railroad":"CSX"   
        }
    ]
}
The following PATCH will update the street, sets the multi-select value for Type of Train and sets HSR Corridor ID to be N/A
PATCH https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings('350152L')?token=<token-value>
Content-type: application/json
{
	"Crossings":
    [
        {
           "CrossingId": "857733N",
           "ReasonId":14,
           "ReportType":"Full Inventory Record ",
           "Railroad":"CSX",
           "TypeTrnSrvcIDs":"11,16,14",
           "Street":"Main",
           "BlockNumb":"12",
           "HscoRrid":"NA"
        }
    ]
}
The following PUT will update field I.7 Do Other Railroads Operate a Separate Track at Crossing? to Yes and UP as one of the Railroad operator, set field I.8 Do Other Railroads Operate Over Your Track at Crossing? to No, and update field I.34 Railroad Contact with the telephone number. It also updates field III.2.D Advance Warning Signs, W10-1, W10-4, and W10-12 with a numeric value or null.
PUT https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings('350152L')?token=<token-value>
Content-type: application/json
{
	"Crossings":
    [
         {
           "CrossingId": "857733N",
           "ReasonId":14,
           "ReportType":"Full Inventory Record ",
           "Railroad":"CSX"   ,
           "SepInd":"1",
           "SepRr1":"UP",
           "SameInd":"2",
           "RrDiv":"NA",
           "DevelTypID":"11",
           "SpselIDs":"11,12",
           "LLsource":"1",
           "Lt1PassMov":"1",
           "RrCont":"8002320144",
           "AdvWarn":"1,2,12",
           "AdvW10_1":"5",
           "AdvW10_2":"3",
           "AdvW10_3":null,
           "AdvW10_4":null,
           "AdvW10_11":null,
           "AdvW10_12":"1"
        } 
    ]
} 
Send multiple Crossing Data for Processing
Multiple crossing can be sent using the POST endpoint. Multiple crossing submissions can process up to 10 crossings at a time.
Note:
Error messages are generated for each submission. This may not provide as much specific information as desired if many crossings are submitted together.
To receive crossing level error reports you should use single Crossing Data requests.
The following POST combines all three requests mentioned in the sections above.
POST https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?token=<token-value>
{
   "Crossings":
    [
      {
        "CrossingId": "852324E",
        "ReasonId": 14,
        "ReportType": "Full Inventory Record",
        "Railroad": "WVRD",
        "StateCD": "41",
        "CntyCD": "41053",
        "CityCD": "410531070",
        "DayThru":  '1',
        "NghtThru": '2',
        "TotalSwt": "3",
        "TotalLtr": "0",
        "RrNarr1": "(X)",
        "ReportingAgencyTypeID":'1'
      },
      {
         "CrossingId":"476229X",
         "ReasonId":14,
         "ReportType":"Full Inventory Record ",
         "Railroad":"EIRC",
         "TypeTrnSrvcIDs":"11,16,14",
         "Street":"Main",
         "BlockNumb":"12",
         "HscoRrid":"NA"
      },
      {
         "CrossingId":"852324E",
         "ReasonId":14,
         "ReportType":"Full Inventory Record ",
         "Railroad":"EIRC",
         "SepInd":"1",
         "SepRr1":"UP",
         "SameInd":"2",
         "RrDiv":"NA",
         "DevelTypID":"11",
         "SpselIDs":"11,12",
         "LLsource":"1",
         "Lt1PassMov":"1",
         "RrCont":"8002320144",
         "AdvWarn":"1,2,12",
         "AdvW10_1":"5",
         "AdvW10_2":"3",
         "AdvW10_3":null,
         "AdvW10_4":null,
         "AdvW10_11":null,
         "AdvW10_12":"1"
      }
   ],
   "isCancelRequest":false
}
  
Send Crossing using XML
Sending the data in XML format is exactly the same as above, except the data has to be formatted as XML and the Content-Type has to be set to application/xml.
                     
POST https://stage.fra.dot.gov/MasterWebService/SecureAPI/gcis/v1/odata/Crossings?token=<token-value>
    Content-type: application/xml
<CrossingProcessRequest>
    <Crossings>
        <Crossing>
        <CrossingId>669335R</CrossingId>
        <PosXing>1</PosXing>        
        <Railroad>BNSF</Railroad>
        <ReasonId>14</ReasonId>
  	<PrempType null="true" />
        <PrfxMilePost>NON</PrfxMilePost>
        <PrvxSign>2</PrvxSign>
        </Crossing>
        <Crossing>
	<CrossingId>393835W</CrossingId>
        <DayThru>0.0</DayThru>
        <Latitude>45.4495350</Latitude>
        <Longitude>-99.3409190</Longitude>
        </Crossing>
    </Crossings>
    <isCancelRequest>false</isCancelRequest>
</CrossingProcessRequest>