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 10000 rows of data at a time, but a user can pick which 10000 rows of data and then return to retrieve the next 10000.

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:

  1. Table Name – At least one table name is required. Up to three table names can be entered.
  2. Column Name – This is an optional entry. Enter a column name and value to limit the results.
  3. OperatorThis 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.
  4. 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.
  5. 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 10000 rows.
  6. Output FormatThis 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:

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

Use this API to search for Hourly UV Index forecast results in a given ZIP Code.

URL

https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/ZIP/{ZIP Code}/{Output Format}
 

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 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 XML: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/ZIP/20050
Hourly UV Index forecast results for ZIP Code 20050 in JSON: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/ZIP/20050/JSON
Hourly UV Index forecast results for ZIP Code 20050 in EXCEL: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/ZIP/20050/EXCEL
Hourly UV Index forecast results for ZIP Code 20050 in CSV: https://iaspub.epa.gov/enviro/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

https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/CITY/{City Name}/STATE/{State Abbreviation}/{Output Format}
 

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 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 XML: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc
Hourly UV Index forecast results for Washington, DC in JSON: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc/JSON
Hourly UV Index forecast results for Washington, DC in EXCEL: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVHOURLY/CITY/washington/STATE/dc/EXCEL
Hourly UV Index forecast results for Washington, DC in CSV: https://iaspub.epa.gov/enviro/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

https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/ZIP/{ZIP Code}/{Output Format}
 

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 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 Hourly 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 XML: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/ZIP/20050
Daily UV Index forecast and alert results for ZIP Code 20050 in JSON: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/ZIP/20050/JSON
Daily UV Index forecast and alert results for ZIP Code 20050 in EXCEL: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/ZIP/20050/EXCEL
Daily UV Index forecast and alert results for ZIP Code 20050 in CSV: https://iaspub.epa.gov/enviro/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

https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/CITY/{City Name}/STATE/{State Abbreviation}/{Output Format}
 

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 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 Hourly 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 XML: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc
Daily UV Index forecast and alert results for Washington, DC in JSON: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/JSON
Daily UV Index forecast and alert results for Washington, DC in EXCEL: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/EXCEL
Daily UV Index forecast and alert results for Washington, DCin CSV: https://iaspub.epa.gov/enviro/efservice/getEnvirofactsUVDAILY/CITY/washington/STATE/dc/CSV

SOAP Web Service

Developers versed in SOAP can utilize the following two services to display daily UV Index and Alert forecasts on any Web site.

  • get UV Index and Alert by Zip Code
  • get UV Index and Alert by City and State

Output for both services are the following:

  • ForecastDate: timestamp for the forecast (next day)
  • Alert: boolean value (true or false) of UV alert
  • Index: integer value of UV index

Port URL - invoke the services from the client application at https://iaspub.epa.gov/uvindexalert/services/UVIndexAlertPort

WSDL URL – view the Web services definitions and descriptions at https://iaspub.epa.gov/uvindexalert/services/UVIndexAlertPort?wsdl