SKYWARN Storm Spotter User Guide
What and Where is it?
The SKYWARN Storm Spotter Status service offers to send you Direct Messages (DM) via Twitter containing the Spotter Information Statement for your chosen location, to keep you aware of the Storm Spotter activation status and forecasts in a passive way.
Why do I want this?
There are times when checking the Hazardous Weather Outlook (HWO) is unfeasible, inconvenient, or inconsistent. The HWOs update between a couple hours to a couple minutes. With this service, if an update occurred within the last hour, you’ll get a DM with the Spotter Activation Statement (up to 114 characters) for your chosen location, and a link to the original report for more information.
The DM will then show up where ever you have chosen to receive them (i.e. text, SMS, twitter app, email, PC, tablet, etc.).
What do I need?
There are very few requirements:
- Create or own a Twitter account
- Willing to follow @NOAAalerts (to receive your Direct Messages, nothing else)
- Less than 2 minutes to choose your location.
That’s it; it’s very simple.
What does it want from me?
During this initial launch phase of version 2, the service is free while testing. Ultimately, a pricing scheme will be rolled out to cover the costs of the necessary API plan from AERIS or additional signup steps will be added to keep it free. Your Twitter information (the little that is stored to make the twitter connection) is neither shared nor stored. The source code is available on Github for anyone to read and verify.
The permissions set for the Twitter Authentication are “Read/Write” for the sole purpose of allowing the service to create the follow-relationship (upon user action) whereby the Authenticating User follows @NOAAalerts to receive the DM alerts. The credentials are not used for reading or sending tweets or DMs on behalf of the user, nor updating your profile, nor will its followers be bothered as a result of this authentication permission level.
How does it work?
Sign into the service with Twitter
This service solely operates on the services offered by Twitter: namely Direct Messages and user authentication. To get started, you’ll need to sign in with your Twitter account. If you don’t have one, you can register for one for free here.
Twitter Authentication page
If you’re already signed into Twitter, you should see something like the image above: your Twitter alias in the top-right, a big “Authorize app” button near the center, and api.twitter.com as the domain. If you’re not already signed into Twitter, you’ll see something like the image below, where you’ll need to give your username and password – again to api.twitter.com in the domain.
The app info in the right-pane will show thepizzy.net’s version of the SKYWARN logo, and some information about this app similar to the description on this page. Once you have clicked the “Authorize app” button, you’ll be redirected to your SKYWARN Spotter Status profile.
SKYWARN Spotter Status profile
Once the redirection is complete, you should see some familiar information like your Twitter alias and avatar. A check will also be done to see if you were already following @NOAAalerts on Twitter – since that is your next step.
If you weren’t already following @NOAAalerts on Twitter, you’ll see a big blue “Follow @NOAAalerts” button on your profile page. You’ll want to go ahead and click that. If you don’t follow @NOAAalerts, the service can’t send you DMs. Two little icons on the left will show your connection status and whether the service can reach you via DM.
Once you are following @NOAAalerts, the blue button disappears, and your connection status will change to green, like below. This is where you get to configure your profile…
Selecting your location
On the left side, there is an “Add Location” button and a “Change Location” link. They do the same thing, and clicking one of those will bring up a dialog where you can select your state, and then your County or Region with County Subsection.
Once you have finished making your selections, click the Save button.
You’ll be redirected back to your profile page, and if any reports for your location have been scanned recently, they’ll be displayed there for you. If there aren’t any, a message will be displayed about when the next scan will run.
If you want to make changes to the selections you’ve made, just click the button showing your location or the “Change Location” link in the left panel to show the location selection dialog again. Select your new location, and then click Save.
Viewing the Storm Spotter forecasts
Due to API cost and usage limits, the service runs at the start of every hour, based on this criteria:
- Gather all the Locations that Users have selected, which have not been updated in the last hour.
- Fetch the HWOs and check for their Issued Timestamp and Spotter Information Statement.
- For any users requesting statements from this location, alert them if the Timestamp is newer and the Spotter Information Statement has changed.
If you’re the first person to choose a particular location, the service will fetch the latest HWO at the top of the next hour.
Once fetched, the HWO will be parsed, cached, alerted and displayed in the center column of the profile page. A new feature with version 2 is the ability to display the cached HWO for users to view by clicking the “Show Cached Advisory” button on their profile page.
In the image above, the HWO issued to include Dallas, TX is shown, and expanded. To view what is currently offered by the National Weather Service, click the “View NWS Source” button on the right of the “Show/Hide Cached Advisory” button
The Twitter Direct Message Alerts
While the Storm Spotter Forecast cards are updating, a DM is sent from the @NOAAalerts Twitter account to all users who have subscribed to the NWS Office locations that have issued new HWOs. If you viewed such a DM on the Twitter website, it would look something like this…
The Direct Messages come in the format: <County, excluding Region descriptor>, <State>: <Spotter Information Statement><Source HWO URL>
The message is comprised of:
- Up to 114 characters (cut off at end-of-word) to contain as much as possible of: County, State, and Spotter Information Statement
- Followed by 4 characters for an ellipsis and a trailing space
- A 22-character Twitter-formated URL to the HWO source page.
Sometimes the NWS will put two Spotter Activation Statements for different, but nearby, geographic locations into the same HWO, in which case you may receive only one of those notifications. Also, the NWS may issue two HWOs back-to-back (the newer one being a correction). In such cases, you will receive whatever is the most recent statement at the start of the next hour.
Usually though, you’ll likely only receive 3-4 DMs during a 24 hour period, except on active weather days. For after-hours silencing, please use your Twitter settings or device settings to restrict the delivery of messages during off-hours.
Disconnecting the Service
If the alerts become too much, or too frequent, there is the option to Disconnect from the service. There is a link in the lower left side of the profile footer to “Disconnect Service.”
Clicking the “Disconnect Service” link will bring up a dialog explaining what is about to happen, to make sure you really want to do go through with it. You can easily sign back up if you change your mind later.
Two things will happen if you click the “Disconnect Service” button on the confirmation dialog:
- Your Twitter account unfollows @NOAAalerts on the Twitter side, preventing future DMs
- Your User record and location selection stored in the database are deleted.
Just like that, it’s a clean break. However, if you change your mind, you can still come back to the service, sign back in with Twitter, and set everything up again from scratch.
- Task – Update TwitterOAUTH plugin #16
Bug fixes; Fixes related to a server move and relative vs static vs display paths
Complete rewrite of the code base to make use of the AERISweather.com API endpoints on a developer account, with throttling limits of 10 requests/minute; 750,000 requests/day.
Added code for tracking API request counts, timestamp and endpoints.
A bug-fix and code formatting release.
A rework and cleanup revision to fix some connection issues.
- #5 Fixed: Restructured the CRON job page to perform the necessary queries outside of the loop
- Cleaned up some DEFINES and commented out some unused queries to remove them from memory
- Updated PHPDocs on some class methods.
Latest release with a couple fixes around database queries and error handling.
- #5 Fixed: Try querying the database, and catch any errors, then try a second time to run the same query. If still fails, error gracefully.
The code has been running for the past 7+hours without incident.
Latest release with a single major fix reducing the frequency of alerts.
- #4 Fixed: Only alert the user if the spotter information statement has changed, not the outlook itself.
This code has been running for the past several weeks without incident.
The next stable release of the code with several issues fixed:
- Updated footer version number for current version
- Drafted a README with workflow descriptions and content
- Moved connection_info.ini to direction inaccessible by the public; fixed hard coded paths to the file and placed in a constant.
- Updated cron_report_check.php to remove test tweets and replace with error DM notifications
- Fixed parsing issue with spotter statements length comparisons
- #2 Fixed alerts for unchanged product updates
On the back-end, I scaled app permissions back to Read/Write after testing (mentioned in ticket #3) to only use the necessary permissions for service functionality. Read/Write was required to create the follow friendship between the user and @NOAAalerts; otherwise Read Only would have been sufficient.
This is the initial release with all intended working functionality:
- Twitter Authentication
- User profile, persistence of National Weather Service city/state locations
- Direct Message when new Hazardous Weather Outlook is updated (new info, new report, etc)
- Follow @NOAAalerts link
- Disconnect Service feature to remove from database and unfollow
Questions, Comments, Feedback
If you have any questions about the service, you can reach me on Twitter: @neotsn
There is a more technical write-up on my blog for this new version of the Storm Spotter Service. You’re welcome to leave questions, comments, and feedback there also in the comments section.