USA Banner

Official US Government Icon

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure Site Icon

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

U.S. Department of Transportation U.S. Department of Transportation Icon United States Department of Transportation United States Department of Transportation

ERG Sharing and Collaboration API

The ERG2020 provides a sharing and collaboration API that is accessed via hyperlinks. All ERG platforms now support this API, leveraging these links to share material information and reference documentation. All ERG links use the https protocol and the www.phmsa.dot.gov/erg domain and path. If the user does not have the ERG application installed or is using the Mac or Windows platform, accessing a shared link will open the DOT website and direct them to the mobile platform downloads. If the user has the iOS or Android version of the ERG2020 installed on their device, a shared link will be treated as a universal link or an app link and will open directly in the respective application. Links can be shared freely between the ERG mobile applications via common text-based messaging channels, such as SMS or email. Alternatively, these links may be created manually using the specification below, allowing partners and external developers to access ERG content directly through this API.

Though the specification below includes example links for all supported languages, any locale-specific link can be opened by a device in another locale. There is no functional difference based on the link's language: opening a French link on an English device will not open the content in French, but will instead display the content in English.

For questions or comments regarding this API, please submit your name, organization, contact information, and feedback to ERGComments@dot.gov. The ERG team strives to make this API accessible and valuable to the developer community. If you are using it, please let us know!

Default URL Components

These components are required of all ERG API links.

URL component Value
Protocol https
Domain www.phmsa.dot.gov
Required Path erg
Functional Path See below. Examples include material, guide, and ref
Example URL: https://phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017

Formatting notes:

  • All parameters and values are case sensitive.
  • Spaces should be replaced with the "%20" unicode character. Likewise, all special characters should be percent-encoded.
  • Numbers should be formatted using the American locale.
Materials

All material links require either a material UN number or a material name. The material will be shown if both the materialUn and materialName parameters are provided and uniquely identify a material; it will also be shown if only the materialUn or the materialName parameter is provided, but the value of that parameter exactly and uniquely identifies a material by UN or name. In any other case where only one of these parameters is provided, search results for the value of that parameter will be shown. Any other case will result in an error.

URL Path: material

 

Parameter Description Required? Default Value
materialUn

The UN of the associated material

This parameter is paired with materialName.

 Either the materialUn or the materialName parameter must be provided. N/A
materialName

The name of the associated material

The name field supports both English and French materials.

Notes:
  • Multiple materials can have the same UN, but no two materials within a single locale will have the same UN and name.
  • There does not exist a one-to-one correspondence between ERG materials in different languages. If a device in one language receives a material link in which the material name is specified in a different language, and no unique and exact match in the current language is found, then the user will be presented with a list of possible matches from which to choose.
 Either the materialUn or the materialName parameter must be provided. N/A
Examples

  1. Open chlorine as a material.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017

    French: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017

  2. Search for materials containing the word "Ammonia".

    English: https://www.phmsa.dot.gov/erg/material?materialName=Ammonia

  3. Search for materials whose UN number contains "14".

    English and French: https://www.phmsa.dot.gov/erg/material?materialUn=14

Protective Distance Data and Maps

Show the protective distance data for the given substance or material. These parameters must be used in combination with either the substance identification parameters or the material identification parameters. In the former case, the catId parameter must be set to 165; in the latter, it should be omitted.

Parameter Description Required? Default Value
lat

The latitude of the location in signed degrees format

Valid range is a decimal from -90.0 degrees to 90.0 degrees.

The latitude must be formatted using the American decimal separator (".").

 Yes* N/A
lon

The longitude of the location in signed degrees format

Valid range is a decimal from -180.0 degrees to 180.0 degrees.

The longitude must be formatted using the American decimal separator (".").

 Yes* N/A
windDir

The wind direction where the spill is taking place

Wind direction is reported by the direction from which it originates. For example, a northerly wind blows from the north to the south, and would have a windDir value of 0. Wind direction is usually reported in cardinal directions or in azimuth degrees. Wind direction is measured in degrees clockwise from due north.

Valid range is an integer from 0 degrees to 360 degrees.

 Yes* N/A
showMap

The flag that signifies whether or not to display the map or protective distance data for the given substance

Possible values:

  • true - Show the actual protective distance map.
  • false - Show the default protective distance data. All other protective distance parameters are ignored.
 Yes* false
spillSize

The size of the spill

Possible values:

  • small
  • large
 No large
timeOfDay

The time of day during which the spill occurred

Possible values:

  • day
  • night
 No night
whereSpilled

The surface on which the spill occurred

This is important for water-reactive materials.

Possible values:

  • land
  • water
 No land
containerType

The type of container

Possible values:

English French
Rail tank car Wagon citerne
Highway tank truck or trailer Citerne routière ou remorque
Agricultural nurse tank Réservoir ravitailleur agricole
Multiple small cylinders Plusieurs petits cylindres
Multiple ton cylinders Plusieurs cylindres d'une tonne
Multiple small cylinders or single ton cylinder Plusieurs petits cylindres ou cylindre unique d'une tonne
No First available container
windSpeed

The wind speed at the spill location

Possible values:

  • low
  • moderate
  • high
 No low
mapType

The type of 2D map to display

Possible values:

  • normal
  • satellite
  • hybrid
 No normal
color

The ARGB value for the color and opacity of the protective distance cone

ARGB values are expressed using 8 hexadecimal digits, with each pair of the hexadecimal digits representing the values of the Alpha, Red, Green and Blue channel, respectively. For example, 80FFFF00 represents 50.2% opaque yellow.

 No 50FFA500
hideLabels The flag that specifies whether or not to show the protective distance labels on the cone (available in WebWISER only)

true - labels will be hidden.

false - labels will be shown

 No false

* These parameters are only required and valid if you choose to display the protective distance map (set showMap equal to true). By default, only the data is displayed, making the map detail irrelevant.

Examples

  1. Show a worst case chlorine spill in Baltimore, MD with a southerly wind direction.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017&lat=39.2906&lon=-76.6092&windDir=180&showMap=true

    French: https://www.phmsa.dot.gov/erg/material?materialName=Chlore&materialUn=1017&lat=39.290600&lon=-76.609200&windDir=180&showMap=true

  2. Open a small chlorine spill in New York, NY with an easterly wind direction during the day.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017&lat=40.7128&lon=-74.0060&windDir=90&spillSize=small&timeOfDay=day&showMap=true

    French: https://www.phmsa.dot.gov/erg/material?materialName=Chlore&materialUn=1017&lat=40.712800&lon=-74.006000&windDir=90&spillSize=small&timeOfDay=day&showMap=true

  3. Open a large chlorine spill that occurred in Washington, DC with a westerly wind direction at night, with a highway tanker truck container, and a moderate wind speed.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017&lat=38.9072&lon=-77.0369&windDir=270&timeOfDay=night&containerType=Highway%20tank%20truck%20or%20trailer&windSpeed=moderate&showMap=true

    French: https://www.phmsa.dot.gov/erg/material?materialName=Chlore&materialUn=1017&lat=38.907200&lon=-77.036900&windDir=270&timeOfDay=night&containerType=Citerne%20routi%C3%A8re%20ou%20remorque&windSpeed=moderate&showMap=true

  4. Open a worst-case chlorine spill in Tampa, FL with a southerly wind, a satellite map type, and an overlay color of lime green with a 25% tranparency.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Chlorine&materialUn=1017&lat=27.9506&lon=-82.4572&windDir=180&mapType=satellite&color=be29ff16&showMap=true

    French: https://www.phmsa.dot.gov/erg/material?materialName=Chlore&materialUn=1017&lat=27.950600&lon=-82.457200&windDir=180&mapType=satellite&color=be29ff16&showMap=true

  5. Open an ammonia spill given all parameters.

    English: https://www.phmsa.dot.gov/erg/material?materialName=Ammonia%2C+anhydrous&materialUn=1005&showMap=true&lat=43.651893&lon=-79.381713&windDir=61&spillSize=large&timeOfDay=night&color=a77716ff&windSpeed=moderate&containerType=Agricultural%20nurse%20tank

    French: https://www.phmsa.dot.gov/erg/material?materialName=Ammoniac,%20anhydre&materialUn=1005&showMap=true&lat=43.651893&lon=-79.381713&windDir=61&spillSize=large&timeOfDay=night&color=a77716ff&windSpeed=moderate&containerType=R%C3%A9servoir%20ravitailleur%20agricole

Guide Pages

Show a specific guide page, referenced by its number.

URL Path: guide

Parameter Description Required? Default Value
number The number of the guide page Yes N/A
Examples

  1. Open Guide Page 141.

    English and French: https://www.phmsa.dot.gov/erg/guide?number=141
Reference Content

Show a piece of reference documentation or a listing of a specific group of documentation from the ERG2020.

Reference documents use OID's (obfuscated identifiers) - hashes that are created within our database. They uniquely identify each topic and document.

URL Path: ref

Parameter Description Required? Default Value
topic The unique OID of the reference topic Yes, unless a doc is provided N/A
doc The unique OID of the reference document Yes, unless a topic is provided N/A

If both parameters are provided and valid, we will default to the document. No error message will be required.

Examples

  1. Open "How To Use Orange Guides".

    English and French: https://www.phmsa.dot.gov/erg/ref?doc=733b7158e171a7542ca75adf29fe9802
IED tool

Show a full listing of IEDs or the data from a specific IED.

URL Path: ied

Parameter Description Required? Default Value
threat

The description of the IED threat

This field can be supplied in any of the supported languages.

 No Null

If the threat field is left empty, the application will open to the list of IED entries (i.e. the reference topic).

BLEVE tool

Show a full listing of BLEVEs or the data from a specific BLEVE.

URL Path: bleve

Parameter Description Required? Default Value
capacity

The capacity of the BLEVE entry

This field must be supplied as just a number, assumed to be in imperial units.

 No Null

If the capacity field is left empty, the application will open to the list of BLEVE entries (i.e. the reference topic).

Examples

  1. Show the data for a BLEVE with a capacity of 26.4 gallons (100 L).

    English and French: https://www.phmsa.dot.gov/erg/bleve?capacity=26.4

ERG 2020 Version 3.1, December 2020

Last updated: Thursday, February 4, 2021