Web Services
Envirofacts is developing web services to facilitate the sharing of its functionality and information. All of the services that are available within Envirofacts will be listed on this tab. Please check back periodically as we are developing many new services.
A RESTful data service API is now available for Envirofacts UV Index Hourly and Daily forecast data.
Searches can now be performed using search parameters such as "BEGINNING with/CONTAINING" and a JSON output is also available.
Envirofacts Data Service API
Envirofacts has developed a RESTful data service API to all of its internal data holdings. This functionality provides a user of Envirofacts with the ability to query any table through the use of a URL. The default output is in XML, which can be utilized in other applications, as well as tools such as Microsoft Excel or Access. Output options of JavaScript Object Notation (JSON), CSV, and Excel can be requested in the URL. The entire Envirofacts database metadata is available online, so that all tables and columns within Envirofacts are documented. Having the table structures available in this manner makes most of Envirofacts data easily available through the service.
To locate tables and columns for use in the Envirofacts Data Service API, please visit the Envirofacts data model page. This page contains links to all of the EPA systems and data models contained within Envirofacts.
Strengths and Limitations of the Envirofacts RESTful Service
This is a simple to use, well-documented way to access multiple data sources without the need of user database connections. The resulting output can be easily used with desktop applications such as Excel or Access, or used in creating Web mash-ups.
The current release of the service, while providing easy access to a tremendous amount and range of data, is limited to querying up to three tables. Also, the output is limited to 10,000 rows of data at a time, but a user can pick which 10,000 rows of data and then return to retrieve the next 10,000.
Constructing a Search
To build a search, users create a URL with a specific set of parameters. This is done by creating a string using the following format:
- Table Name – At least one table name is required. Up to three table names can be entered.
- Column Name – This is an optional entry. Enter a column name and value to limit the results.
- Operator – This is an optional entry. This parameter allows users to pass in an operator with the query. Default output is "=" and does not require an operator, but users can enter "<", " >", "!=", "BEGINNING", "CONTAINING", operators as well via the URL. The "BEGINNING" operator will return rows where the start of a column value is equal to the search value. While the "CONTAINING" will return rows where the search value is contained within the column value. Additional details on operators is available in the EF Data Service API complete documentation.
- Column Value – This is an optional entry. The column value is queried against the database without modification. Use the program system Model to double check the case for the value.
- Rows – This is an optional entry. Specify the rows to display by entering 'rows/ <first_row> : <last_row>' Results numbering starts at 0. So to get the first five hundred rows enter rows/0:499 If “rows” is not specified, the default is the first 10,000 rows.
- Output Format – This is an optional entry. The default output is in XML; however, output options of JSON, CSV or Excel can be requested in the URL. The output format is not case sensitive.
- Count – This is an optional entry and not shown in the above URL. Count will show the total number of records that will be returned when using the URL without the count. This is available only with the default XML output.
For example:
- https://data.epa.gov/efservice/tri_facility/state_abbr/VA/rows/499:504
returns result set records 500 to 505 from the TRI_FACILITY table where STATE_ABBR = ‘VA’. - https://data.epa.gov/efservice/pcs_permit_facility/major_discharge_indicator/M
returns the first 10,000 records from PCS_PERMIT_FACILITY table where the MAJOR_DISCHARGE_INDICATOR = ‘M’. - https://data.epa.gov/efservice/TRI_FACILITY/state_abbr/HI/TRI_REPORTING_FORM
returns results from the TRI Facility and TRI Reporting Form tables where the state is HI in the TRI Facility table. - https://data.epa.gov/efservice/TRI_FACILITY/state_abbr/VA/TRI_REPORTING_FORM/TRI_CHEM_INFO/EXCEL
returns results from the TRI Facility, TRI Reporting Form and TRI Chem Info tables where the state is VA in the TRI Facility table in Excel format . - https://data.epa.gov/efservice/tri_facility/zip_code/BEGINNING/600/JSON
returns results from the TRI_FACILITY table where ZIP CODE "Begins With" 60085 in a JSON format. - https://data.epa.gov/efservice/tri_facility/state_abbr/VA/CSV
returns result from the TRI_FACILITY table where STATE_ABBR = ‘VA’in a CSV format. - https://data.epa.gov/efservice/tri_facility/COUNT
returns results showing the total number of records matching the user input.
More information on EF Data Service API
UV Index
Envirofacts provides two approaches for retrieving UV Index data thru web services: a RESTful data service API and a SOAP (Simple Object Access Protocol) web service. The information is searchable by ZIP Code and city, state, making it useful for any organization, either local or national. Users do not have to leave your site to see the forecast. The UV Index Overview provides additional information on the data. Both approaches are detailed below.
RESTful Data Service API
This functionality provides a user of UV Index data, within Envirofacts, the ability to query daily or hourly forecast data through the use of a URL. The four APIs for retrieving UV Index forecast information are:
- Get the Hourly UV Index forecast by ZIP Code
- Get the Hourly UV Index forecast by City and State
- Get the Daily UV Index forecast by ZIP Code
- Get the Daily UV Index forecast by City and State
Get the Hourly UV Index forecast by ZIP Code
Use this API to search for Hourly UV Index forecast results in a given ZIP Code.
URL
Parameters
Parameter | Description | |
---|---|---|
ZIP Code | A valid United States Postal Service (USPS) ZIP Code or Postal Code. | |
Output Format | The API can retrieve results as XML, JSON, EXCEL or CSV. Set the Output Format to one of these values (XML, JSON, EXCEL, CSV). By default the API will return results as XML. |
Results
Output Column | Description | |
---|---|---|
Order | Used in sequentially ordering the output, ensuring the data is presented in correct chronological order. | |
ZIP | The ZIP Code for which the Hourly UV Index forecast results have been retrieved. | |
DATE_TIME | The date and time of the UV Index forecast value. The date/time is displayed in the local time of the requested ZIP Code. | |
UV_VALUE | The UV Index forecast value. |
Example API Requests
Hourly UV Index forecast results for ZIP Code 20050 in JSON: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/ZIP/20050/JSON
Hourly UV Index forecast results for ZIP Code 20050 in EXCEL: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/ZIP/20050/EXCEL
Hourly UV Index forecast results for ZIP Code 20050 in CSV: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/ZIP/20050/CSV
Get the Hourly UV Index forecast by City and State
Use this API to search for Hourly UV Index forecast results in a given City, State.
URL
Parameters
Parameter | Description | |
---|---|---|
City Name | A valid City Name in the United States. | |
State Abbreviation | The abbreviation of the state that the city resides in. | |
Output Format | The API can retrieve results as XML, JSON, EXCEL or CSV. Set the Output Format to one of these values (XML, JSON, EXCEL, CSV). By default the API will return results as XML. |
Results
Output Column | Description | |
---|---|---|
Order | Used in sequentially ordering the output, ensuring the data is presented in correct chronological order. | |
City | The city for which the Hourly UV Index forecast results have been retrieved. | |
State | The state in which the city resides in. | |
DATE_TIME | The date and time of the UV Index forecast value. The date/time is displayed in the local time of the requested City, State. | |
UV_VALUE | The UV Index forecast value. |
Example API Requests
Hourly UV Index forecast results for Washington, DC in JSON: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc/JSON
Hourly UV Index forecast results for Washington, DC in EXCEL: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc/EXCEL
Hourly UV Index forecast results for Washington, DC in CSV: https://data.epa.gov/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc/CSV
Get the Daily UV Index and Alert forecast by Zip Code
Use this API to search for Daily UV Index forecast and alert results in a given ZIP Code.
URL
Parameters
Parameter | Description | |
---|---|---|
ZIP Code | A valid United States Postal Service (USPS) ZIP Code or Postal Code. | |
Output Format | The API can retrieve results as XML, JSON, EXCEL or CSV. Set the Output Format to one of these values (XML, JSON, EXCEL, CSV). By default the API will return results as XML. |
Results
Output Column | Description | |
---|---|---|
ZIP | The ZIP Code for which the Daily UV Index forecast results have been retrieved. | |
UV_VALUE | The UV Index forecast value. | |
UV_ALERT | A character indicating if there is a UV Index alert issued for this area on the forecast day. |
Example API Requests
Daily UV Index forecast and alert results for ZIP Code 20050 in JSON: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/ZIP/20050/JSON
Daily UV Index forecast and alert results for ZIP Code 20050 in EXCEL: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/ZIP/20050/EXCEL
Daily UV Index forecast and alert results for ZIP Code 20050 in CSV: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/ZIP/20050/CSV
Get the Daily UV Index and Alert forecast by City and State
Use this API to search for Daily UV Index forecast and alert results in a given City, State.
URL
Parameters
Parameter | Description | |
---|---|---|
City Name | A valid City Name in the United States. | |
State Abbreviation | The abbreviation of the state that the city resides in. | |
Output Format | The API can retrieve results as XML, JSON, EXCEL or CSV. Set the Output Format to one of these values (XML, JSON, EXCEL, CSV). By default the API will return results as XML. |
Results
Output Column | Description | |
---|---|---|
City | The city for which the Daily UV Index forecast results have been retrieved. | |
State | The state in which the city resides in. | |
UV_VALUE | The UV Index forecast value. | |
UV_ALERT | A character indicating if there is a UV Index alert issued for this area on the forecast day. |
Example API Requests
Daily UV Index forecast and alert results for Washington, DC in JSON: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/JSON
Daily UV Index forecast and alert results for Washington, DC in EXCEL: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/EXCEL
Daily UV Index forecast and alert results for Washington, DCin CSV: https://data.epa.gov/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/CSV