diff --git a/README.md b/README.md index fd3a26d4..ab739f2f 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,36 @@ Below is a listing of every possible machine-readable summary produced by Dark Sky. The listing is recursive so as to better describe how the various structural components interact. +### Status Information + +Instead of producing a summary of weather information, we may sometimes generate +a status message indicating an error of some sort. Such messages may take one of +the following forms: + +* `["sentence", [STATUS_MESSAGE, STATUS_TYPE, REASON]]` + +`STATUS_MESSAGE` may be one of the following: + +* `"next-hour-forecast-status"`: we have information to convey about our + hyperlocal next-hour forecasts + +`STATUS_TYPE` may be one of the following: + +* `"unavailable"`: no forecast is available for this request +* `"partially-unavailable"`: only a partial forecast is available for this request +* `"temporarily-unavailable"`: no forecast is available for this request, but we + expect it to be available again in the future + +`REASON` may be one of the following: + +* `"station-offline"`: we cannot generate a forecast because all nearby weather + stations are offline (e.g. for maintenance) +* `"station-incomplete"`: we cannot generate a forecast because of gaps in the + coverage of all nearby weather stations (e.g. radar beams are blocked by + local terrain) + +`"next-hour-forecast-status"`, `"unavailable"`, `"partially-unavailable"`, `"temporarily-unavailable"`, `"station-offline"`, and `"station-incomplete"` are not used in any other forms. + ### Moment Summaries When the API is producing a text summary for a single moment in time (that is, @@ -250,18 +280,13 @@ capitalized, and the sentence is to end with a period). For text summaries for the next hour (that is, `minutely.summary`), summaries of the following formats are produced: -* `["sentence", ["next-hour-forecast-status", PERSISTENCE, STATION_STATUS]]` * `["sentence", ["for-hour", WEATHER_CONDITION]]` * `["sentence", ["starting-in", PRECIPITATION_TYPE, DURATION]]` * `["sentence", ["stopping-in", PRECIPITATION_TYPE, DURATION]]` * `["sentence", ["starting-then-stopping-later", PRECIPITATION_TYPE, DURATION, DURATION]]` * `["sentence", ["stopping-then-starting-later", PRECIPITATION_TYPE, DURATION, DURATION]]` -The first case is an error case when nearby radar stations are experiencing issues -and describe the persistence of the problem as well as some information on the -stations' status. - -Except for the first two case, each such summary only takes precipitation into +Except for the first case, each such summary only takes precipitation into account, and tells how the intensity of precipitation will vary over the next hour or so.