Open flagbrad opened 2 years ago
Ready for USGS internal peer review, link available on internal Teams chat (or view content/api_catalog.md)
Hi Brad,
FIrst, great job. It's clear a lot of work went into this and I like the overall tone. I was only able to make it through the "Water Quality Portal" section. Here are my comments:
Intro
smaller group of users
results in a broken link for me"...our water-data web services (APIs)"
OGC sensorthings API
Datastreams@iot.navigationLink
and did not find a result. Is this the expected outcome? I did find Observations@iot.navigationLink
in the link.OGC API
Water quality portal
" Some of our users have expressed ~express~ interest in a wide format which is ~in~ a simplified gridded output where constituents define columns, laboratory samples define rows, and numeric results and qualifiers are in each grid cell."
Looks good to me, the main thing I noticed was this link was a 404: https://webvadevvs04.er.usgs.gov/updates/user_operationalized_pull/. But might just the dev tier?
Comments from @wdwatkins and @padilla410 have all been incorporated and will be in a forthcoming pull request. Thank you!
Great work on this. Overall a great post with a wealth of info. I learned a lot! I actually would love to see this formed into a permanent reference page for USGS water data services since blogs are somewhat ephemeral. This is the clearest round-up of all the available data services I have ever seen.
Now for my few critiques:
You introduce "JSON structure" without explaining what JSON is. I know it's outside the scope of this post to explain JSON, but I think you need to at least define it as a common web data structure and link to an explainer. I would maybe add a footnote about it, or move up the one you have (#3) to the first mention of JSON and expand on it.
This part from the OGCSensorThinngs API section:
Try iterating through this array searching for the 5-digit USGS parameter code you are interested in (often, it’s 00060 for Discharge or 00065 for Gage Height).
Is a bit confusing because the URL the reader gets from Step 2 results in array like this:
In which each of those objects in the array is fairly complex object with more objects nested, and the parameter code is not even at the root of that object. I get what you mean when you say iterate through it, but will your audience get it? If web developers is the audience, then probably fine. If not, maybe clarify this part.
or for the more stalwart reader there is the official SensorThings specification.
Be careful here. It implies if the reader is intimidated by the full spec, they are not stalwart (loyal, reliable, hardworking). I may use something more like 'adventurous' or just 'interested'.
For most large rivers and non-fractured groundwater systems, one daily value per day is adequately if not wholly representative of that water resource–less data but just as informative as dozens of instantaneous values per day. But for small rivers and sundry hydrological phenomena, a daily value is an expedient trade-off that discards useful information
I appreciate the writing / voice here, but it may be a little on the verbose side for a public-friendly plain language blog. Consider rephrasing.
All comments from @BlakeDraper have been incorporated into a forthcoming pull request. Thank you!
Addressed comments in issue #615. Also addressed comments from lstanish as follows:
And answers to some questions from lstanish:
Revisions completed based on management review. After pull request is merged, api_catalog.md is ready for publication to the production tier.
A high-level overview of major USGS water-data APIs, conveyed in a logical ordering that encourages uptake of newer APIs preferentially over older legacy ones.