Road Condition Reporting System (RCRS) Event Data Service API

1. Introduction
2. Audience
3. What Is Web API?
4. Requesting Access
5. Usage Limits
6. RCRS_Event_Data Service
   1. liveEvents Method
      • Properties
      • Example
   2. plannedEvent Method
      • Properties
      • Example
   3. winterConditions Method
      • Properties
      • Example
   4. Code Tables
      • ConditionID
      • County
      • Direction
      • EventType
      • LaneStatus
      • PoliceJurisText
      • ReportOrgID
      • VehicleRestrictText
      • VehicleRestrictTier
      • AffectedLanes
      • Occurs

Introduction

This document summarizes the RCRS_Event_Data external web service of the PennDOT Road Condition Reporting System (RCRS). This service provides Statewide event and winter road condition information to outside agencies and vendors.

Audience

This document is intended for agency or vendor developers who want to obtain RCRS event information for use in external systems. It provides an introduction to using the RCRS_Event_Data service and reference material on the available parameters.

What Is Web API?

From Wikipedia.org:

A web API is an application programming interface (API) for either a web server or a web browser. It is a web development concept, usually limited to a web application's client-side (including any web frameworks being used), and thus usually does not include web server or browser implementation details such as SAPIs or web browser engine APIs unless publicly accessible by a remote web application.

Endpoints

Endpoints are important aspects of interacting with server-side web APIs, as they specify where resources lie that can be accessed by third party software. Usually the access is via a URI to which HTTP requests are posed, and from which the response is thus expected. Endpoints need to be static, otherwise the correct functioning of software that interacts with it cannot be guaranteed. If the location of a resource changes (and with it the endpoint) then previously written software will break, as the required resource can no longer be found at the same place. As API providers still want to update their web APIs, many have introduced a versioning system in the URI that points to an endpoint, for example the Clarifai API: The endpoint for the tagging functionality within the web API has the following URI: "https://api.clarifai.com/v1/tag/". The "/v1/" part of the URI specifies access to the first version of the web API. If clarifai decides to update to version two, they can do this while still maintaining support for third party software that uses the first version.

Resource vs. service

Although "web API" is sometimes considered a synonym for web service, Web 2.0 web applications have moved away from SOAP-based web services towards more cohesive collections of RESTful web resources.[5] These RESTful web APIs are accessible via standard HTTP methods by a variety of HTTP clients including browsers and mobile devices. They have advantages over web services in that they tend to be less difficult to develop and less resource intensive (and thus usually run faster) since they do not need to perform as many data conversions as required by a SOAP-based service APIs.

Requesting Access

Gaining access to the service is a two step process. The first step is to create a user account in PDAuth. The process for creating a user account in PDAuth is different for external users than internal users. Internal users are users who have a CWOPA account. Directions for creating a user account in PDAuth for internal and external users are listed below.

Step 1 - Create PDAuth Account
Internal Users
Internal users that already have a CWOPA account must login to PDAuth using their CWOPA credentials. After logging into PDAuth for the first time, their user account will be automatically created using their CWOPA credentials.

External Users
External users must first create a user account in PDAuth by selecting 'Create Account' from the Log in window.

Enter the account information and click 'Sign Up'.

A verification email will be sent to the email address that was used to create the user account and will contain an activation link. The user account can not be used until the account is activated using the activation link. The activation link will direct users to a Password Reset window that allows them to create their password. Strong password requirements are enforced during the password creation process.

Step 2 - Request Access
Once the PDAuth account has been created in step 1, access to the RCRS_Event_Data service must be requested. To request access, send an email to penndotdata@pa.gov with your PDAuth username and a brief description of your reason for access. After access has been granted, you will receive a notification email from PDAuth that your request has been approved. The PDAuth credentials can now be used to acess the RCRS_Event_Data service.

Service Limitations

Currently there are no request limitations for this service. Any limitations added in the future will be included in this section.

RCRS_Event_Data Service

The RCRS_Event_Data service is a Web API service that can be accessed from any client that can make an HTTP request and process a JSON response. Each method listed below can be accessed using a standard HTTP GET request. The format of the web service requests and responses will be described in this document.

This service uses HTTP Basic Authentication for credential authentication and authorization. User credentials must be encoded in base 64 and set in the authorization header of the service request. An example for setting the authorization header is shown below.

Secure Socket Layer (SSL) must be enabled by prepending "https://" to each service request.

Methods

liveEvents Method

The liveEvents method of the RCRS_Event_Data service returns Pennsylvania road events that are active in RCRS at the time of the request.

Properties

Example

HTTP Request

The following is a sample HTTP GET request using jQuery AJAX. The placeholders shown need to be replaced with the PDAuth credentials.

$.ajax({
url: 'https://gisdata.penndot.pa.gov/RCRS_Event_Data/api/RCRS/liveEvents',
type: 'GET',
data: '',
dataType: 'json',
beforeSend: function (xhr) {
xhr.setRequestHeader("Authorization", "Basic " + btoa(username + ":" + password));
},
success: function (result, status, XMLHttpRequest) {
//on success
},
error: function (XMLHttpRequest, status, error) {
//on error
}
});

HTTP Response

The following is a sample HTTP response from the liveEvents method.

{
"Values": [
{
"ActualDateTimeOpened": "",
"DateTimeVerified": "2019-08-27 14:31",
"IsHazmat": "F",
"HazmatPlacardID": "",
"HazmatMaterialName": "",
"IsFatality": "F",
"IsSchoolBus": "F",
"IsCommercialVehicleRollover": "F",
"IsCrashInConstructionZone": "F",
"IsPennDOTPropertyAndOrEmployeeInvolved": "F",
"IsAutonomousVehicle": "F",
"IsTransitOrTourBus": "F",
"IsFirstResponderWithMajorInjuryOrFatality": "F",
"IsTrain": "F",
"IsAmishConveyance": "F",
"IsAircraft": "F",
"IsBridgeStrike": "F",
"RestrictedSpeedValue": "",
"VehicleRestrictText": "",
"EventID": 581,
"EventClass": "3",
"EventType": "roadwork",
"ReportOrgID": "11",
"Facility": "HITE RD / TAWNEY RUN RD",
"Direction": "eastbound",
"FromLoc": "Intersection of PITTSBURGH MILLS BL in FRAZER [2TWP]",
"FromLocLatLong": "40.5662781980593,-79.7956370235785",
"FromLocMileage": "",
"FromLocDirection": "",
"ToLoc": "Intersection of MURRAY HILL RD / + BUTLER LOGAN RD in FRAZER [2TWP]",
"ToLocLatLong": "40.5705014313923,-79.7906322059793",
"ToLocMileage": "",
"ToLocDirection": "",
"IncidentLoc": "",
"IncidentLocLatLong": "",
"IncidentLocMileage": "",
"IncidentLocDirection": "",
"DateTimeEventOccurs": "2019-08-27 14:30",
"CreateTime": "2019-08-27 14:31:55",
"LastUpdate": "2019-08-27 14:31:55",
"State": "PA",
"County": "02",
"CountyName": "ALLEGHENY",
"LaneStatus": "lane restriction",
"AffectedLanes": "",
"VehicleRestrictTier": "",
"DetourInEffect": "F",
"IsInterstate": "F",
"Description": "Roadwork on HITE RD / TAWNEY RUN RD eastbound between PITTSBURGH MILLS BL and MURRAY HILL RD / + BUTLER LOGAN RD. There is a lane restriction.",
"DateTimeNotified": "2019-08-27 14:31",
"IncidentMuniName": "FRAZER [2TWP]",
"PoliceJurisText": "",
"Is511Event": "F",
"StateRouteNo": "1014",
"CountyFrom": "02",
"CountyFromName": "ALLEGHENY",
"BeginSegPoint": "00540627",
"CountyTo": "02",
"CountyToName": "ALLEGHENY",
"EndSegPoint": "00602118",
"CountyInc": "",
"CountyIncName": "",
"IncSegPoint": "",
"IsTemporaryTrafficControlDevicesInUse": "F",
"HaulerRestrictionInEffect": "F",
"IsHaulerRestriction24x7": "F",
"NoPermitTravel": "F",
"MaxLengthRestriction": 0,
"MaxWidthRestriction": 0,
"MaxHeightRestriction": 0,
"MaxWeightRestriction": 0,
"EventRepetitionDetails": {
"RepetitionID": "One Time Event",
"Occurs": "N/A",
"SkipHolidays": "N/A",
"StartDate": "N/A",
"EndDate": "N/A",
"DailyStartTime": "N/A",
"DailyEndTime": "N/A"
},
"Detours": [
{
"DetourID": 6982,
"Direction": "E",
"VehicleType": "B",
"ColorID": "4",
"TotalLength": 5.144,
"Narrative": ""
}
]
}
]
}

plannedEvents Method

The plannedEvents method of the RCRS_Event_Data service returns Pennsylvania road events that are planned in RCRS at the time of the request.

Properties

Example

HTTP Request

The following is a sample HTTP GET request using jQuery AJAX. The placeholders shown need to be replaced with the PDAuth credentials.

$.ajax({
url: 'https://gisdata.penndot.pa.gov/RCRS_Event_Data/api/RCRS/plannedEvents',
type: 'GET',
data: '',
dataType: 'json',
beforeSend: function (xhr) {
xhr.setRequestHeader("Authorization", "Basic " + btoa(username + ":" + password));
},
success: function (result, status, XMLHttpRequest) {
//on success
},
error: function (XMLHttpRequest, status, error) {
//on error
}
});

HTTP Response

The following is a sample HTTP response from the plannedEvents method.

{
"Values": [
{
"EventID": 276684,
"EventClass": "14",
"EventType": "special event",
"ReportOrgID": "04",
"Facility": "PA - 093",
"Direction": "both directions",
"FromLoc": "Intersection of DEWEY ST in NESCOPECK [BORO]",
"FromLocLatLong": "41.0523311193851,-76.215080887329",
"FromLocMileage": "",
"FromLocDirection": "",
"ToLoc": "Intersection of MONTGOMERY ST in NESCOPECK [BORO]",
"ToLocLatLong": "41.0521299646895,-76.224771669308",
"ToLocMileage": "",
"ToLocDirection": "",
"IncidentLoc": "",
"IncidentLocLatLong": "",
"IncidentLocMileage": "",
"IncidentLocDirection": "",
"DateTimeEventOccurs": "2016-08-20 15:00",
"CreateTime": "2016-07-28 08:02:33",
"LastUpdate": "2016-07-28 08:02:33",
"State": "PA",
"County": "40",
"CountyName": "LUZERNE",
"LaneStatus": "closed",
"AffectedLanes": "Left Lane, Center",
"VehicleRestrictText": "",
"VehicleRestrictTier": "",
"DetourInEffect": "F",
"IsInterstate": "F",
"Description": "Special event on PA 93 both directions between DEWEY ST and MONTGOMERY ST. All lanes closed.",
"DateTimeNotified": "2016-07-28 07:54",
"DetourDescription": "",
"IncidentMuniName": "NESCOPECK [BORO]",
"PoliceJurisText": "",
"Is511Event": "F",
"StateRouteNo": "0093",
"CountyFrom": "40",
"CountyFromName": "LUZERNE",
"BeginSegPoint": "03900496",
"CountyTo": "40",
"CountyToName": "LUZERNE",
"EndSegPoint": "04000000",
"CountyInc": "",
"CountyIncName": "",
"IncSegPoint": "",
"IsTemporaryTrafficControlDevicesInUse": "F",
"HaulerRestrictionInEffect": "F",
"IsHaulerRestriction24x7": "F",
"NoPermitTravel": "F",
"MaxLengthRestriction": 0,
"MaxWidthRestriction": 0,
"MaxHeightRestriction": 0,
"MaxWeightRestriction": 0,
"EventRepetitionDetails": {
"RepetitionID": "276684",
"Occurs": "Weekdays",
"SkipHolidays": "NO",
"StartDate": "2016-08-25",
"EndDate": "2016-09-04",
"DailyStartTime": "08:00",
"DailyEndTime": "16:00"
},
"Detours": [
{
"DetourID": 6982,
"Direction": "E",
"VehicleType": "B",
"ColorID": "4",
"TotalLength": 5.144,
"Narrative": ""
}
]
}
]
}

winterConditions Method

The winterConditions method of the RCRS_Event_Data service returns Pennsylvania roadway winter condition information active in RCRS at the time of the request.

Properties