USGS Streamflows on Twitter
The U.S. Geological Survey has thousands of sites across the United States regularly recording recent streamflow readings. This data is available on their web site and can be downloaded as a tab-delimited file and more recently as an experimental web service.
This service allows you to use Twitter to get the most current streamflow data (stage, streamflow and water temperature) for a stream, lake or river, providing it is monitored by the USGS. This is most useful if you do not have high speed Internet available, such as you are on the road, but you can send and receive cell phone text messages. (If you are online, you can also see these measurements on the Twitter site, via many Twitter clients, or it can appear in your email inbox.) At this time only streamflow, gage height and water temperature are served, as they are the most common. Note: not all sites record all these types of data. You will receive the data if it is served by the site.
Getting Started
The service works with using by sending requests via the Twitter reply syntax (@stream_flow) or via direct messages (d stream_flow). If sent using @stream_flow, the result is public and the response will be identified as for you. Whereas if you use a direct message, the reply is private.
For either replies or direct messages, for the service to work you must first follow "stream_flow". Do not follow "streamflow". This is a different Twitter account. Use the underscore! "stream_flow" goes by the name "Streamflow service" so you can search by that too.
To use the service by sending direct messages, additional steps are required:
- First, "stream_flow" must follow you. Once every 15 minutes a process is run in which new followers of "stream_flow" are automatically followed. You can tell you are being followed by "stream_flow" when you see that "stream_flow" is one of your followers.
- If you have set up your Twitter account so that you cannot be automatically followed, you will have to take an additional step and manually approve the request for "stream_flow" to follow you:
- To see if this applies to you, check Settings, Account tab. If "Protect my updates" is checked, either temporarily uncheck it or go to the Notices tab and check "Email when someone starts following me".
- If you receive an email when you get a follower request, use the link in the email to permit "stream_flow" to follow you.
Getting readings for a site
There are two ways to get current streamflow readings for a site: by supplying all or part of a site name, or by site number.
Direct message: d stream_flow description
Via a reply: @stream_flow description
where description is either a numeric USGS site number or a full or partial USGS site name.
For replies, you must start with @stream_flow followed by at least one space. If @stream_flow appears anywhere else, a retweet will be assumed and the reply will be ignored.
You should get back a direct message or reply within two minutes, but it depends in part on whether you are using a Twitter client. It may also depend on how often it polls your Twitter account. A cron job is run on this server once a minute to check and process any new direct messages or replies for "stream_flow". Time for the reading is reported in site time. Note: USGS sites typically transmit every one to four hours, so the most current available reading may be an hour or more behind the current time. Here is an example of output as a direct message:
01645762 S F LITTLE DIFFICULT RUN ABOVE MOUTH NR VIENNA, VA :: stage 1.49 feet, flow 3.5 cfs, water temp 50 deg F @ 9:00 PM 11/12/2009. Provisional data subject to revision.
Get a reading by sending all or part of a site name
You have to know the part or all of the USGS site name. Often if you know the lake, stream or river where the site is located along with a nearby city that is enough, but if unsure use the USGS Waterwatch Google Maps Site. Obviously site names are easier to remember than site numbers.
If you know the site name, be as specific as you can and be careful with your spelling! Case does not matter when entering site names. If you provide part of the site name and it matches more than one site, you will get a reply back indicating the number of matching sites and asking you to be more specific. You will get a reply which is something like this:
@markdhamill 41 sites with names matching "Mississippi" were found. Please be more specific.
Direct message: d stream_flow Goose Creek Leesburg
Via a reply: @stream_flow Goose Creek Leesburg
If you want to narrow the search to a particular state or postal code, end your tweet with a slash followed immediately by the two digit postal code. The postal code can be in either lower or upper case. For example:
d stream_flow Goose Creek Leesburg/AK returns no sites but
d stream_flow Goose Creek Leesburg/va returns one site
Get a reading by sending a site number
If you know the site number, that's easiest.
Direct message: d stream_flow 01644000
If you don't know the site number, first find it on the USGS Waterwatch Google Maps Site. Since this service is most useful as a text message service, you might wish to record the site names and their associated numbers and take them with you on the road with you. Record the site numbers of interest that appears when you put your mouse over the colored dot. The site number is typically 8 characters, but is sometimes longer, ex: 06115200. At present only sites with a USGS agency code (the vast majority of sites) are served.
Getting a Streamflow Reading using your cell phone
- Make sure your cell phone is configured to receive direct messages from Twitter. See above.
- Send a text message to 40404 with the following (minus the quotes) using either direct message or Twitter reply (@stream_flow) syntax
Getting a Streamflow Reading while on twitter.com
- Replies will appear in your conversation thread. You may wish to refresh the conversation after a minute or so.
- If sent as a direct message:
- Look for the Direct Messages link on the right.
- Use the Send drop down box to select "stream_flow".
- Enter the site number as the message and press Send. Refresh the page in a minute or so to see the streamflow reading.
Receiving a Streamflow reading as an email
To receive direct messages while on twitter.com go to Settings and select the Notices tab. If sending direct messages, may sure to check the "Email when I receive a new direct message" checkbox and press Save.
Questions and Support
Why did Twitter not send me a new reading for site X even though I just got a reading a little while ago?
This seems to be an issue only when you use the reply syntax. It appears that Twitter will examine recent outgoing tweets and if the nothing has changed it figures you are either being careless or you are a spamming its servers. You can probably infer that the reading has not changed even though you requested it explicitly.
If you query a different site, then query the original site, Twitter will see it as a new request.
What quality of service is provided?
This service is considered experimental however I have no plans to discontinue it. Once configured it is a pretty simple application to run. Should the U.S. Geological Survey provide a similar service at some point I will provide a notification to all followers on how to use their service and after a reasonable period of time retire the service.
How do I provide feedback or get support?
I appreciate any feedback you have on the service so it can be more useful. To reach me, you can either send me email or if you want register and post the question in my support forum. Select the forum under the Web Services category.