Graph Image API
The graph image API allows users to download an image version of the new dynamic hydrograph that is on the next generation monitoring location pages.
Recently, the Water Data for the Nation (WDFN) development released a new real-time site page . One of the most common pieces of feedback that we received about the hydrograph on the new monitoring location pages was that users need a way to save an image of a given hydrograph. In the classic pages , these graphs are already images, generated by the server using a command line tool called gnuplot . It was easy enough to expose the endpoint that generated those images:
https://waterdata.usgs.gov/nwisweb/graph?agency_cd=USGS&site_no=09380000&parm_cd=00060&period=7Legacy graph image, rendered server-side using gnu-plot.
These images are all over the internet, and an important service provided by the Water Data for the Nation project. Unfortunately, the structure of this approach was showing its age. Users wanted more than just static plots on the water data pages, they wanted interactive figures, which we have built in the new monitoring location pages . At the same time, one of the most commonly requested features on new monitoring location pages was an image version of the new, interactive hydrograph, so we know we needed to do something.
However, the new approach to building graphs is not nearly so straightforward to make an image from, as they are dynamically generated in the web browser using a tool called D3 . Replicating the environment of a browser was a non-trivial task, but with the major advances in browser automation with tools like puppeteer , we were able to generate a reasonable solution .
So now, it is possible to render a contemporary graph from water data for the nation, while only needing to use the venerable <img> tag, as you can see below:
<figure>
<img
src="https://labs.waterdata.usgs.gov/api/graph-images/monitoring-location/09380000/?parameterCode=00060"
alt="A line graph showing 7 days of hydrological data. The line is orange, with black axes"
>
<figcaption>
Future graph image, rendered server-side using client-side code with puppeteer
</figcaption>
</figure>Future graph image, rendered server-side using client-side code with puppeteer
https://labs.waterdata.usgs.gov/api/graph-images/monitoring-location/09380000/?parameterCode=00060
The graph image project is a work in progress and this is a first step to meeting users’ requests for easy image downloads. We have added openAPI based documentation so that users can easily see how to customize the images using available query parameters. The user can now customize the size, title, time period, and time series ID.
In the future, we plan to add additional features to the graph image server, including
- more gracefully handling when no data are returned
- additional data elements
- different kinds of graphs beyond the basic hydrograph
- making it possible to embed dynamic content, rather than just images, in third party pages.
Try it out and email WDFN@usgs.gov to let us know how it works for you!
Related Posts
How to build Sensorthings API Queries
February 23, 2023
REST Information GETS The OGC SensorThings API is a RESTful API that is based on the Odata protocol. For the public facing service, only GETs are supported. Major functions and endpoint of the API: GET Description labs.waterdata.usgs.gov/sta/v1.1/ Get index - provides an overview of the SensorThings response. labs.waterdata.usgs.gov/sta/v1.1/Type Get all of type - includes Locations, Things, Data Streams, Observed Properties, or Observations. labs.waterdata.usgs.gov/sta/v1.1/Type(id) Get one of a type - requests information related to a specific device.
Explore USGS Water Data API Basics
May 19, 2023
Use the Explore USGS Water Data API for quick access to national-scale water data. Get Started The Explore USGS Water Data API was created using GraphQL to provide a way to request specific data from multiple sources. This API lets clients scale and focus results to retrieve only what is needed. Key Components A request to the Explore USGS Water Data API includes three components. Query: The process used to read or fetch values.
Sample SensorThings Queries and Responses
February 23, 2023
Sample Calls with Responses List All Object Types This request provides an overview of the SensorThings response. Each value consists of a “name” that provides the name of the SensorThings class together with a “url” that provides access to all objects of this class. The following provides an overview of the SensorThings response at https://labs.waterdata.usgs.gov/sta/v1.1/ : Response for All Objects { "value": [ { "name": "Datastreams", "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams" }, { "name": "MultiDatastreams", "url": "https://labs.
SensorThings API - Quick Start
February 23, 2023
Use the SensorThings API to access national-scale data for quicker application development and the ability to map those results. This API provides users with a flexible way to interconnect data, devices, and applications over the Web. Get Started USGS created JSON sample APIs as a way to quickly access and use USGS available data. What’s New? Plot my API results on a Map SensorThings makes it easy to put information on a map by natively supporting a geoJSON output.