How to Access and Use ATTAINS Web Services

Page | 1
How to Access and Use ATTAINS Web Services
Version: 5/16/2019
Purpose: To explain how to use ATTAINS Web Services to access public ATTAINS data. This document explains
how to generate the URL to query an ATTAINS REST service. It provides the base URL for each service, and the
query parameters available for that service.
Audience: These instructions access public data, so an ATTAINS login ID is not required.
Contents
1 General Information on ATTAINS Web Services 1
2 Summary Services 2
2.1 State Summary Service 2
2.2 HUC12 Summary Service 2
3 Domain Values Service 3
4 Assessment Units Service 4
5 Assessments Service 6
6 Actions Service 8
1 General Information on ATTAINS Web Services
Web services provide the ability for one computer to communicate data to another computer in a standard way.
It allows for data from one system to be easily incorporated into another application, without needing to locally
host the data. Many mobile device applications use web services to acquire data and then format and display
the data the way the designer chooses.
ATTAINS web services are formatted using JavaScript Object Notation (JSON) and use Representational State
Transfer (REST) protocols. Basically, that means you can build a query of the web service if you know the
appropriate building blocks: the web address of the starting point, the name of the service, one or more data
fields that you would like to query, and the search criterion you want to use for each data field that you chose.
ATTAINS web services require an exact match to the criterion you enter. You cannot search for partial matches.
In addition, case syntax for each query parameter and search criterion is important.
Data returned from an ATTAINS JSON REST web service can be viewed in a browser such as Chrome by installing
a JSON parser browser add-in (such as JSON Formatter for Chrome). This method can work for smaller amounts
of data. However, for larger amounts of data, we recommend using other software that can parse the data into
tabular formats such as Microsoft Excel 2016 or the Power Query extension for Excel, or R statistical software
packages that can consume JSON. This document does not contain instructions for those software packages.

-------
Page | 2
2 Summary Services
This section refers to services that provide summary information.
2.1 State Summary Service
This service provides summary information for assessed Uses for an Organization (State, Territory or Tribe) and
Integrating Reporting Cycle. The Organization ID for the state, territory or tribe is required. If a Reporting Cycle
isn't provided, the service will return the most recent cycle. If a Reporting Cycle is provided, the service will
return a summary for the requested cycle.
Base URL and service: https://attains.epa.gov/attains-public/api/usesStateSummarv?
Input Parameter
Description / Notes
organizationld*
Search criterion - Provides summary info for only the Organization Identifier
provided. This is not the same as the state abbreviation. Each Organization is
associated with a geographic state, but there can be multiple Organizations
inside a state boundary (e.g., a state org and a tribal org), so the query must
provide the specific Organization ID. The list of available Organization IDs can
be obtained from the Domain values service by looking at orgStateCode.
reportingCycle
Search criterion - Filter the summary to a specific reporting cycle in terms of
the four-digit year the reporting cycle ended (e.g., for the 4/2/2016 -
3/31/2018 reporting cycle, the four-digit reporting cycle is "2018"). If left
blank, the service will return the most recent cycle.
* Denotes a required query parameter.
Example 1: If I wanted to query for a summary of Uses in the most recent cycle of data from Tennessee (Org ID:
TDECWR), then I would use this URL:
https://attains.epa.gov/attains-public/api/usesStateSummarv?organizationld=TDECWR
Example 2: If I wanted to query for a summary of Uses in the 2016 cycle of data from South Dakota (Org ID:
SDDENR), then I would use this URL:
https://attains.epa.gov/attains-public/api/usesStateSummarv?organizationld=SDDENR&reportingCycle=2016
2.2 HUC12 Summary Service
This service was primarily built for How's My Waterway 2.0. It provides summary information for a 12-digit
Hydrologic Unit Code (HUC12), based on the Assessment Units in the HUC12. Watershed boundaries may cross
state boundaries, so this service may return Assessment Units from multiple Organizations (such as neighboring
states). This service returns a list of the Assessment Units in the HUC12, as well as the size and percentage of
those Assessment Units that have been assessed as Good, Unknown, or Impaired. It also provides summaries by
EPA IR Category for the Use Groups used in How's My Waterway 2.0.
Base URL and service: https://attains.epa.gov/attains-public/api/hucl2summary?
Input Parameter
Description / Notes
hue*
Search criterion - The HUC12 to be summarized.
* Denotes a required query parameter.

-------
Page | 3
Example 1: If I wanted to query for a summary of all Assessment Units in the 12-digit HUC of 020700100204
(regardless of Organization), I would use this URL:
https://attains.epa.gov/attains-public/api/hucl2summary?huc=020700100204
3 Domain Values Service
This service provides information on allowed values in ATTAINS. Using the base URL without any query
parameters returns a list of the various domain types. Using the base URL with a query parameter of
"?domainName=" and one of the domains that was returned from just the base URL will provide the domain
values (or allowed values) for that domain.
Base URL: https://attains.epa.gov/attains-public/api/domains?
Here is the list of domainName options available to use:
ActionDocumentType
ActionStatusType
ActionType
AgencyCode
AssessmentBasisCode
AssessmentConfidenceCode
AssessmentDocumentType
AssessmentTypeCode
AssessmentUnitDocumentType
ContactType
CycleDocumentType
DelistingReasonCode
DocumentFileType
DocumentTypeCode
LoadAllocationUnitCode
LocationTypeCode
LocationTypeValue
MethodTypeCode
MetricType
OrgStateCode
ParameterAttainmentCode
ParameterGroupCodeType
ParameterName
ParameterQualifierCode
ParameterStatus
PollutantSourceType
ReportingCycleStatusCode
SizeEstimationMethodCode
SizeSourceScaleText
SourceName
StatelRCategoryCode
Statuslndicator
Su rveyCatego ryT ype
SurveyDocumentType
Su rveyStatu sTy pe
SurveyUseType
TrendCode
TrophicStatusCode
UnitType
UseAttainmentCode
UseClassType
UseClassUse
UseName
UseQualifierCode
WaterTypeCode
WaterTypeGroup
WaterTypeUnitsCode
Input Parameter
Description / Notes
domainName
Search criterion - select a domain name from the list above, to obtain the
valid values for that domain.
context
Search criterion - when used in conjunction with a domainName, it will
return the list of values for that context. This is useful for returning a list of
values that are allowed for an Organization. For example, when used in
conjunction with the domainName=UseName, the context value would be
the Organization ID.
Example 1: This service call does not require any query parameters. Calling it without any query parameters
will return a list of the different domain names that are available. To do so, I would use this URL without any
query parameters: https://attains.epa.gov/attains-public/api/domains

-------
Page | 4
Example 2: If I wanted to query for allowed Parameter Names, I would use this URL:
https://attains.epa.gov/attains-public/api/domains?domainName=ParameterName
Example 3: If I wanted to query for the list of Organization IDs, I would use this URL:
https://attains.epa.gov/attains-public/api/domains?domainName=OrgStateCode
Example 4: If I wanted to query for the allowed Use Names for the state of Tennessee (Org ID: TDECWR), I
would use this URL:
https://attains.epa.gov/attains-public/api/domains?domainName=UseName&context=TDECWR
4 Assessment Units Service
This service is for retrieving basic information about the Assessment Units, such as a list of all the Assessment
Unit IDs used in a state or county. This service does NOT provide assessment decision data.
• One or more of these Input Parameters must be included: assessmentUnitldentifier OR stateCode OR
organizationld. Additional Input Parameters will further refine the results.
• If multiple values are allowed for a query input parameter, they should be separated by a comma (ex:
assessmentUnitldentifier=AssessmentUnitl,AssessmentUnit2).
Base URL: https://attains.epa.gov/attains-public/api/assessmentUnits?
Input Parameter (any
combination)
Description/Notes
assessmentUnitldentifier*
Search criterion - Filters the list of assessment units to one or more specific
assessment units. Multiple values can be provided.
stateCode*
Search criterion - Filters the list of assessment units to only those having a
state code matches one in the provided list of states. Multiple values can be
provided.
organizationld*
Search criterion - Filters the list of assessment units to only those having an
organization ID that matches one in the provided list of IDs. Multiple values
can be provided.
epaRegion
Search criterion - Filters the list of assessment units to only those having an
EPA region that matches one in the provided list of regions. Multiple values
can be provided.
HUC
Search criterion - Filters the list of assessment units to only those which have
a location type of HUC and the location value matches one in the provided list
of HUCs. Multiple values can be provided.
county
Search criterion - Filters the list of assessment units to only those which have
a location type of county and the location value matches one in the provided
list of counties. Multiple values can be provided.

-------
Page | 5
Input Parameter (any
combination)
Description/Notes
assessmentUnitName
Search criterion - Filters the list of assessment units to only those having an
assessment unit name matching the provided value.
lastChangeLaterThanDate
Search criterion - Filters the list of assessment units to only those last
changed after the provided date. Can be used in conjunction with
LastChangeEarlierThanDate to retrieve assessment units changed within a
date range. If LastChangeEarlierThanDate is also provided, then
LastChangeLaterThanDate must be earlier than LastChangeEarlierThanDate.
Date format must be like "2005-10-16T14:00:00-06:00" or "2005-10-16".
lastChangeEarlierThanDate
Search criterion - Filters the list of assessment units to only those last
changed before the provided date. Can be used in conjunction with
LastChangeLaterThanDate to retrieve assessment units changed within a date
range. If LastChangeLaterThanDate is also provided, then
LastChangeEarlierThanDate must be later than LastChangeLaterThanDate.
Date format must like "2005-10-16T14:00:00-06:00" or "2005-10-16".
statuslndicator
(A="Active", R="Retired") Search Criterion - Filters the list of assessment
units to only those currently in the specified status.
returnCountOnly
("Y"/"N") - Option - Causes the method to return only the count of
assessment units that match the query search criteria. If you leave this blank,
the default is "N".
* One or more query parameters with an asterisk must be provided.
Example 1: If I wanted to return a list of all the Assessment Units in the state of Alabama (stateCode: AL), I
would use this URL:
https://attains.epa.gov/attains-public/api/assessmentUnits?stateCode=AL
Example 2: If I wanted to return just a count of the number of Assessment Units in Alabama (stateCode: AL), I
would use this URL:
https://attains.epa.gov/attains-public/api/assessmentUnits?stateCode=AL&returnCountOnlv=Y
Example 3: If I wanted to return a list of all the Assessment Units in Autauga County in Alabama (stateCode:
AL), I would use this URL:
https://attains.epa.gov/attains-public/api/assessmentUnits?stateCode=AL&county=Autauga County
Note: A web browser may replace the space in the URL with "%20", such as in the county name, above, so the
link may become:
https://attains.epa.gov/attains-public/api/assessmentUnits?stateCode=AL&countv=Autauga%20Countv
Example 4: If I wanted to return all the basic information about Assessment Unit ID "AL03150201-0107-200" in
Alabama, I would use this URL (Note: Assessment Unit IDs must be unique within the Organization ID. You can
query without including the Organization ID, but if multiple Organizations have used the same Assessment Unit

-------
Page | 6
ID, the service will return each matching Assessment Unit ID):
https://attains.epa.gov/attains-public/api/assessmentUnits?assessmentUnitldentifier=AL03150201-0107-200
5 Assessments Service
This service retrieves Assessment decisions for an Organization from a single reporting cycle. It returns the
result from the most recent Assessment cycle status for the cycle (e.g., EPA Final Action status if it exists,
otherwise it would return results from the Organization Final Submittal status).
• One or more of these Input Parameters must be included: assessmentUnitldentifier OR state OR
organizationld. Additional Input Parameters will further refine the results.
• If multiple values are allowed for a query input parameter, they should be separated by a comma (ex:
assessmentUnitldentifier=AssessmentUnitl,AssessmentUnit2).
Base URL: https://attains.epa.gov/attains-public/api/assessments?
Input Parameter
Description / Notes
assessmentUnitldentifier*
Search criterion - Specify which specific assessment unit assessment within
the given reporting cycle to retrieve. Multiple values can be provided.
state*
Search criterion - Filter the list of reporting cycle assessments to those only
from the specified state.
organizationld*
Search criterion - Filter the list of reporting cycle assessments to only those
"belonging to" the specified organization.
reportingCycle
Search criterion - Filter the list of assessments to only those of a specific
reporting cycle in terms of the four-digit year the reporting cycle ended (e.g.
for the 6/1/2016 - 5/31/2018 reporting cycle the four-digit reporting cycle is
"2018"). If left blank, the default is the current cycle relative to the current
date (returns the most recent).
listedAs303d
(Y/N) - Search criterion - Filter the list of reporting cycle assessments to only
those who's assessment units are on the 303d list.
use
Search criteria - Filter the list of reporting cycle assessments to only those
associated with the specified uses. Multiple uses may be listed.

-------
Page | 7
Input Parameter
Description / Notes
useSupport
Search criterion - Filter the list of reporting cycle assessments to only those
fully supporting the specified uses or that are threatened. Multiple
UseSupports may be listed. The allowed values for this parameter are X = Not
Assessed, 1 = Insufficient Information, F = Fully Supporting, N = Not Supporting,
and T = Threatened. Values X, 1, F, and N filter based solely on the
UseAttainmentCode field of an Assessment. However, the last value (T) filters
on a combination of the UseAttainmentCode and the Threatenedlndicator
where the UseAttainmentCode = 'F' and Threatenedlndicator = 'Y'.
parameter
Search criterion - Filter the list of reporting cycle assessments to only those
associated with one or more of the specified parameters. Multiple
parameters may be listed.
parameterStatusName
Search criterion - Filter the list of assessments to only those assessments
where the assessment has one or more associated parameters that are in the
provided status. Valid values for this criterion are: "Meeting Criteria",
"Cause", "Observed Effect." Multiple parameterStatusNames may be listed.
probableSource
Search criterion - Filter the list of reporting cycle assessments to only those
"having" the specified ProbableSource(s). Multiple values can be provided.
agencyCode
(E="EPA", S="State", T="Tribal") - Search criterion - Filter the list of reporting
cycle assessments by the type of agency responsible for the assessment.
delistingStatus
(Y/N) - Search criterion - Filter the list of reporting cycle assessments by
whether the assessment's assessment unit ID is or is not in the delisted waters
list for the same reporting cycle.
irCategory
Search criterion - Filter the list of assessments to only those having one of the
specified IR Categories. Multiple values can be provided.
statelRCategoryCode
Search criterion - Filter the list of reporting cycle assessments to include only
those having one of the provided codes (ON USES OR ON CAUSES).
multicategorySearch
(Y/N) - Specifies whether to search at multiple levels. If this parameter is set
to "Y" then the query applies the StatelRCategoryCode at the Assessment,
UseAttainment, and Parameter levels; if the parameter is set to "N" it looks
only at the Assessment level.
lastChangeLaterThanDate
Search criterion - Filter the list of reporting cycle assessments to only those
last changed after the provided date. Can be used in conjunction with
LastChangeEarlierThanDate to retrieve assessments changed within a date
range. If LastChangeEarlierThanDate is also provided, then
LastChangeLaterThanDate must be earlier than LastChangeEarlierThanDate.
Date format must be like "2005-10-16T14:00:00-06:00" or "2005-10-16".

-------
Page | 8
Input Parameter
Description / Notes
lastChangeEarlierThanDate
Search criterion - Filter the list of reporting cycle assessments to only those
last changed before the provided date. Can be used in conjunction with
LastChangeLaterThanDate to retrieve assessments changed within a date
range. If LastChangeLaterThanDate is also provided, then
LastChangeEarlierThanDate must be later than LastChangeLaterThanDate.
Date format must be like "2005-10-16T14:00:00-06:00" or "2005-10-16".
returnCountOnly
(Y/N) - Option - Causes the method to return only the count of assessments
that match the query search criteria. If you leave this blank, the default is "N".
* One or more query parameters with an asterisk must be provided.
Example 1: If I wanted to get a list of the Assessment decisions for all the Assessment Units in South Dakota
(Organization ID: SDDENR) for the 2016 reporting cycle, I would use this URL (leaving out the reportingCycle
query parameter will return the most recent reporting cycle):
https://attains.epa.gov/attains-public/api/assessments?organizationld=SDDENR&reportingCycle=2016
Example 2: If I wanted to get a list of all the Assessment Units in South Dakota for the most recent cycle that
have a Probable Source of "GRAZING IN RIPARIAN OR SHORELINE ZONES", then I would use this URL:
https://attains.epa.gov/attains-public/api/assessments?organizationld=SDDENR&probableSource=GRAZING IN
RIPARIAN OR SHORELINE ZONES
Example 3: If I wanted to see the most recent Assessment decision of a specific Assessment Unit ID (such as
Assessment Unit ID: "SD-CH-R-BOX_ELDER_02"), I would use this URL:
https://attains.epa.gov/attains-public/api/assessments?organizationld=SDDENR&assessmentUnitldentifier=SD-
CH-R-BOX ELDER 02
If I wanted to see the Assessment decision for the same Assessment Unit for a different reporting cycle, I would
need to specify the reporting cycle:
https://attains.epa.gov/attains-
public/api/assessments?organizationld=SDDENR&reportingCvcle=2016&assessmentUnitldentifier=SD-CH-R-
BOX ELDER 02
Example 4: If I wanted to see all the Assessments in the state of Tennessee (state: TN) where the overall EPA
Integrated Reporting Category is category 5, I would use this URL (since I didn't specify a Reporting Cycle, it will
return the most recent reporting cycle):
https://attains.epa.gov/attains-public/api/assessments?state=TN&irCategory=5
Example 5: Similar to example 4, if I wanted to see all the Assessments in Tennessee where the overall EPA
Integrated Reporting Category is category 4A, I would use this URL (since I didn't specify a Reporting Cycle, it will
return the most recent reporting cycle):
https://attains.epa.gov/attains-public/api/assessments?state=TN&irCategorv=4A

-------
Page | 9
6 Actions Service
This service is for retrieving data about Actions (e.g., TMDLs, 4B Actions, Alternative Actions, Protection
Approach Actions).
• One or more of these Input Parameters must be included: actionldentifier, OR assessmentUnitldentifier
OR stateCode OR organizationldentifier. Additional Input Parameters will further refine the results.
• If multiple values are allowed for a query input parameter, they should be separated by a comma (ex:
actionldentifier=Actionl,Action2).
Base URL: https://attains.epa.gov/attains-public/api/actions?
Input Parameter
Description/Notes
actionldentifier*
Search criterion - Specifies exactly which action to retrieve. Multiple values
may be provided.
assessmentUnitldentifier*
Search criterion - Filters the list of actions to only those associated with any
(i.e. at least one) of the provided assessment unit IDs, plus any statewide
actions (Statewide Actions will not be available in ATTAINS version 1). Multiple
values may be provided.
stateCode*
Search criterion - Filters the list of actions to those only "belonging to" the
specified state.
organizationldentifier*
Search criterion - Filters the list of actions to only those "belonging to" one of
the specified organizations. Multiple values may be specified.
parameterName
Search criterion - Filters the list of actions to only those associated with any
(i.e. at least one) of the provided parameters. Multiple values may be
provided.
pollutantName
Search criterion - Filters the list of actions to only those associated with any
(i.e. at least one) of the provided pollutants. Multiple values may be provided.
actionTypeCode
Search criterion - Filters the list of actions to only those of the specified
ActionTypeCodes. Multiple values may be specified.
agencyCode
(S=State, E=EPA, T=Tribal) - Search criterion - Filters the list of actions to only
those of the specified agency code. Multiple values may be specified.
pollutantSourceTypeCode
Search criterion - Filters the list of actions to only those whose
PollutantSourceTypeCode matches the value(s) passed. Multiple values may be
provided.
actionStatusCode
Search criterion - Filters the list of actions to only those currently having one
of the provided ActionStatusCode. Multiple values may be specified.

-------
Page | 10
Input Parameter
Description/Notes
completionDateLaterThan
Search criterion - Filters the list of actions to only those having a
CompletionDate later than the value passed. Date format must be like "2005-
10-16T14:00:00-06:00" or "2005-10-16".
completionDateEarlierThan
Search criterion - Filters the list of actions to only those having a
CompletionDate earlier than the value passed. Date format must be like
"2005-10-16T14:00:00-06:00" or "2005-10-16".
tmdIDateLaterThan
Search criterion - Filters the list of actions to only those having a TMDLDate
later than the value passed. Date format must be like "2005-10-16T14:00:00-
06:00" or "2005-10-16".
tmdIDateEarlierThan
Search criterion - Filters the list of actions to only those having a TMDLDate
earlier than the value passed. Date format must be like "2005-10-16T14:00:00-
06:00" or "2005-10-16".
lastChangeLaterThanDate
Search criterion - Filters the list of actions to only those last changed after the
provided date. Can be used in conjunction with LastChangeEarlierThanDate to
retrieve actions changed within a date range. If LastChangeEarlierThanDate is
also provided, then LastChangeLaterThanDate must be earlier than
LastChangeEarlierThanDate. Date format must be like "2005-10-16T14:00:00-
06:00" or "2005-10-16".
lastChangeEarlierThanDate
Search criterion - Filters the list of actions to only those last changed before
the provided date. Can be used in conjunction with LastChangeLaterThanDate
to retrieve actions changed within a date range. If LastChangeLaterThanDate
is also provided, then LastChangeEarlierThanDate must be later than
LastChangeLaterThanDate. Date format must be like "2005-10-16T14:00:00-
06:00" or "2005-10-16".
returnCountOnly
(Y/N) - Option - Causes the method to return only the count of actions that
match the query search criteria. If you leave this blank, the default is "N".
* One or more query parameters with an asterisk must be provided.
Example 1: If I wanted to retrieve all the Actions for the state of Alabama (state code: AL), I would use this URL:
https://attains.epa.gov/attains-public/api/actions?stateCode=AL
Example 2: If I wanted to retrieve all the information about a specific Action ID (including any documents
associated with it), I would use this URL:
https://attains.epa.gov/attains-public/api/actions?actionldentifier=R8-ND-2018-03
Example 3: If I wanted to retrieve all the Actions for the Organization ID SDDENR (South Dakota), I would use
this URL:
https://attains.epa.gov/attains-public/api/actions?organizationldentifier=SDDENR

-------