1. Using Python to Interact with the EPA WATERS Web Services
Jon Goodall
Hydroinformatics
Fall 2014
This work was funded by National Science Foundation Grants EPS and EPS

2. EPA Waters
“The Watershed Assessment, Tracking & Environmental Results System (WATERS) unites water quality information previously available only from several independent and unconnected databases.”

3. WATERS Web Services
Description: “WATERS provides a suite of interoperable services that expose components that perform complex analysis and supporting strategic datasets, such as NHD, NHDPlus, and WBD.”
Source:

4. Web and Database Services
The WATERS Web and Database services provide open interfaces to complex analyses.
These services make extensive use of the National Hydrography Dataset (NHD)
Designed as loosely coupled modular units, the services are developed in a common architecture.
The HTTP Services provided REST-like access to the WATERS database services.
Source:

5. NHD = National Hydrography Dataset

6. REST REST = Representational State Transfer
You can think of this as an alternative to SOAP that we discussed and you used previously in this course.
Most people seem to prefer REST because you can simply enter a URL into a web browser and see the response.
The response is often structured text that uses either XML or JSON.
Wikipedia page has further details if you are interested:

7. What is JSON? JSON = JavaScript Object Notation
A way of structuring data in a machine-readable way.
An alternative to XML
Thread on Stackoverflow.com on XML vs JSON:
You can read more details on the Wikipedia page:

8. Back to the EPA WATERS Web Services…
You can find a list of the available services with documentation here:
We will use the Name Service in today’s class as an example:

9. Name Service
Name service documentation is here:
Brief description: “Advanced query function to find water feature names and provide general location information for NHDPlus features.”

10. How do you use these services?
Some example use cases of the WATERS services are here:
I used Firebug, a web development plug-in to Firefox, to see the web service calls used by the example software (see screen shot on next page and I will demonstrate in class).
I was told, but did not test myself, that the Chrome DevTools could also be used for this purpose.

12. The URL for the service

13. Response from Web Service
success({ "output":{ "feature_id":null,"results":[{ "styleUrl":"#.namesrv_results","feature_id":" ","feature_name":"JAMES RIVER","feature_class":"STREAM","primary_state":"VA","primary_state_fips":"51","primary_county":"ISLE OF WIGHT","primary_county_fips":"093","gnis_primary_stem":"JAMES","gnis_primary_hydro":"RIVER","gnis_primary_dir":null,"gnis_secondary_stem":null,"gnis_secondary_hydro":null,"gnis_secondary_dir":null,"resolution":3,"source_schema":"NHDPLUS","source_table":"NHDFLOWLINE_NP21","subbasin":null,"ftype":null,"fcode":null,"gnis_centroid_geom":{"type":"Point","coordinates":[ , ]},"mbr_geom":{"type":"Polygon","coordinates":[[[ , ],[ , ],[ , ],[ , ],[ , ]]]},"shape":null}]},"status":{ "submission_id":null,"status_code":0,"status_message":null,"execution_time": ,"output_bytes":853}})

14. Comments on URL and response
In the URL you will see
pFullText=James+River
pSourceTable=nhdflowline
pState=VA
These are the search criteria I entered in the CodePen interface
In the response you will see
"gnis_centroid_geom":{"type":"Point","coordinates":[ , ]},
“Geometry representing the centroid of the result record as defined by GNIS.”
"mbr_geom":{"type":"Polygon","coordinates":[[[ , ],[ , ],[ , ],[ , ],[ , ]]]},"shape":null}]},
“Geometry representing the maximum bounding rectangle of the matching NHD feature. Note that in the case that the matching NHD record is a single point, that point will be stored in this field.”

15. Testing the Result using Google Maps
Note that you need to flip the coordinates provided by the service when you input them into Google maps

16. Challenge Problem #1
Change the URL provided earlier to find a water feature of interest to you.
Enter the coordinates returned by the service into Google Maps to verify that you got what you expected.

17. Repeat Using Python
Suppose you wanted to create a “search tool” capable of geolocating an NHD feature given its name and state.
We have already shown how to get the response from a URL using Python
import urllib2
response = urllib2.urlopen(<URL String Here>).read()
There are JSON libraries in Python we can use to extract the lat/lon coordinates of the centroid point

18. Challenge Problem #2
Write a Python script that returns the centroid coordinates for an NHD feature given its name and location.
My solution is in the class Github site:

19. What you learned today…
You were introduced to REST
Can you describe the differences between REST and SOAP?
You were introduced to JSON
Can you describe the differences between JSON and XML?
You were introduced to the concept of using Web services for analytics vs. simply providing data

20. Plan for Thursday’s Class
We will look at other services in the EPA WATER Web Services
I will discuss your assignment that will ask you to further evaluate and build on the EPA WATER Web Services.
The USGS/EPA team behind these want to hear your opinion! With your permission, we will share your assignment solution with the NHD development team.