jenna
/
gnome-shell-extension-openweather
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
784 Commits
5 Branches
1 Tag
6.3 MiB
 
 
 
 
 
Tag: Branch: Tree: cd050b652a
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'cd050b652a'
${ noResults }
gnome-shell-extension-openw.../The Dark Sky Forecast API D...

666 lines
33 KiB
Raw Blame History

The Dark Sky Forecast API </>
v2 Forecast API
The Forecast API lets you query for most locations on the globe, and
returns:
* Current conditions
* Minute-by-minute forecasts out to 1 hour (where available)
* Hour-by-hour forecasts out to 48 hours
* Day-by-day forecasts out to 7 days
There are two main API calls. The first <#forecast_call> returns the
current forecast (for the next week):
|https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE|
The second <#time_call> lets one query for a specific time, past or
future (for many places, 60 years in the past to 10 years in the future):
|https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE,TIME|
*Note to Dark Sky API users*: The old docs can be found here </docs>.
Details on migrating to the new API can be found at the bottom of the
page <#migration>.
Changelog
* *3 Dec 2014:* Added Russian to the list of supported languages.
* *23 Sep 2014:* Added Portuguese and Bosnian to the list of supported
languages.
* *14 Aug 2014:* Added Polish and Pig Latin (!?) to the list of
supported languages.
* *29 Jul 2014:* Added Italian to the list of supported languages.
* *11 Jun 2014:* Added Spanish to the list of supported languages.
* *29 May 2014:* Added the |lang| option <#options>.
* *7 Jan 2014:* Added the |moonPhase| property to data points.
* *10 Dec 2013:* Added the MADIS <#data-sources> data source.
* *5 Dec 2013:* Added the |nearestStormDistance| and
|nearestStormBearing| properties to data points.
* *15 Aug 2013:* Added the |apparentTemperature| properties to data
points.
* *17 Jul 2013:* Added the |description| property to severe weather
alerts <#alerts>.
* *15 Jul 2013:* Added the RTMA and SREF weather models
<#data-sources>, and the |X-Forecast-API-Calls| response header
<#response-headers>.
* *22 May 2013:* Added the |extend| option.
* *6 May 2013:* Added string date format to time machine requests.
* *17 Apr 2013:* Added |dewPoint| and |ozone| properties to data points.
* *9 Apr 2013:* Added the |ca| and |auto| unit options, and added
|precipIntensityMax| and |precipIntensityMaxTime| properties on
daily data points.
* *1 Apr 2013:* Added the |exclude| option.
* *29 Mar 2013:* Deprecated the |si| option, replacing it with the
|units| option. When upgrading, be advised that |windSpeed| is now
in meters per second, rather than in kilometers per hour. (*Edit 9
Apr 2013:* one can now use |?units=ca| to precisely emulate the
functionality of |?si|. Please update any code using the deprecated
functionality at your earliest convenience.)
* *26 Mar 2013:* Initial version.
API Libraries
Looking to include Forecast in your app? These wrapper libraries should
make it quick and easy to do so:
* Official Ruby Wrapper Library
<https://github.com/darkskyapp/forecast-ruby> by David Czarnecki
<https://github.com/czarneckid>
* Android Client Wrapper Library
<https://github.com/pequots34/Forecast> by Christopher Brown
<https://github.com/pequots34>
* C++ Wrapper Library
<https://github.com/errantlinguist/Forecast.io-CPP> by Todd Shore
<https://github.com/errantlinguist>
* C# Wrapper Library <https://github.com/f0xy/forecast.io-csharp> by
Charl Cilliers <https://github.com/f0xy>
* Portable C# Wrapper Library
<https://github.com/jcheng31/ForecastPCL> by Jerome Cheng
<https://github.com/jcheng31>
* CFML Wrapper Library <https://github.com/DannyCork/ForecastCFML> by
Danny Cork <https://github.com/DannyCork>
* Clojure Wrapper Library
<https://github.com/jdhollis/forecast-clojure> by J. D. Hollis
<https://github.com/jdhollis>
* Erlang Wrapper Library <https://github.com/derek121/forecast> by
Derek Brown <https://github.com/derek121>
* Go Wrapper Library <https://github.com/mlbright/forecast> by
Martin-Louis Bright <https://github.com/mlbright>
* Java Wrapper Library <https://github.com/dvdme/forecastio-lib-java>
by David Ervideira <https://github.com/dvdme>
* Java Wrapper Library <https://github.com/kushanj1/ForecastIOLibrary>
by Kushan Jayatilleke <https://github.com/kushanj1>
* JavaScript Wrapper Library
<https://github.com/iantearle/forecast.io-javascript-api> (with a
PHP-based proxy) by Ian Tearle <https://github.com/iantearle>
* Node.JS Wrapper Library
<https://github.com/mateodelnorte/forecast.io> by Matt Walters
<https://github.com/mateodelnorte>
* Node.JS Wrapper Library <https://github.com/jonezy/reckon/> by Chris
Jones <https://github.com/jonezy>
* Node.JS Wrapper Library
<https://github.com/soplakanets/node-forecastio> by Serhiy
Oplakanets <https://github.com/soplakanets>
* Objective-C Wrapper Library
<https://github.com/iwasrobbed/Forecastr> by Rob Phillips
<https://github.com/iwasrobbed>
* Objective-C Wrapper Library <https://github.com/carlj/libFIOApi> by
Carl Jahn <https://github.com/carlj>
* iOS XCode Project Template
<https://github.com/brandonemrich/ForecastKit> by Brandon Emrich
<https://github.com/brandonemrich>
* Perl Wrapper Library
<http://search.cpan.org/~martyloo/Forecast-IO-0.21/lib/Forecast/IO.pm>
by Martin-Louis Bright <https://github.com/mlbright>
* PHP Wrapper Library
<https://github.com/tobias-redmann/forecast.io-php-api> by Tobias
Redmann <https://github.com/tobias-redmann>
* PHP Wrapper Library <https://github.com/guhelski/forecast-php> by
Guilherm Uhelski <https://github.com/guhelski>
* PHP Wrapper Library <https://github.com/CNG/ForecastTools>
(supporting multiple, simultaneous calls) by Charlie Gorichanaz
<https://github.com/CNG>
* Python Wrapper Library <https://github.com/ZeevG/python-forcast.io>
by Ze'ev Gilovitz <https://github.com/ZeevG>
* R Wrapper Library <https://github.com/hrbrmstr/Rforecastio> by Bob
Rudis <https://github.com/hrbrmstr>
* Unofficial Ruby Wrapper Library
<https://github.com/vigosan/forecast_io> by Vicent Gozalbes
<https://github.com/vigosan>
* Scala Wrapper Library <https://github.com/film42/forecast-io-scala>
by Garrett Thornburg <https://github.com/film42>
Additionally, Gerard Davison <https://github.com/kingsfleet> has
provided a JSON Schema <https://github.com/kingsfleet/rest-metadata> of
the API, and Alex Handy has provided a CodeEnvy IDE
<https://codenvy.com/factory?id=7jdszo9m4un5m2ql> for a Java API wrapper
of our API.
Finally, please note that all of the above API wrappers (except for the
official Ruby wrapper) are unofficial: we cannot provide support for
them! If you have any questions about them, please contact the library's
author.
The Forecast Call
|https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE|
|APIKEY| should be your Dark Sky API key. |LATITUDE| and |LONGITUDE|
should be the geographic coordinates of a location in decimal degrees.
/(Please note that the base domain for this API request is
|api.forecast.io|, not |api.darkskyapp.com|.)/
The response will be a JSON-formatted object with the following
properties defined:
* |latitude|: The requested latitude.
* |longitude|: The requested longitude.
* |timezone|: The IANA timezone name for the requested location (e.g.
|America/New_York|). This is the timezone used for text forecast
summaries and for determining the exact start time of daily data
points. /(Developers are advised to rely on local system settings
rather than this value if at all possible: users may deliberately
set an unusual timezone, and furthermore are likely to know what
they actually want better than our timezone database does.)/
* |offset|: The current timezone offset in hours from GMT.
* |currently|: A /data point/ (see below) containing the current
weather conditions at the requested location.
* |minutely|: A /data block/ (see below) containing the weather
conditions minute-by-minute for the next hour. /(This property’s
name should be read as an adjective—analogously to “hourly” or
“daily” and meaning “reckoned by the minute”—rather than as an
adverb meaning “meticulously.” Yes, we know that this is not proper
English. No, we will not change it. Complaints to this effect will
be deleted with utmost prejudice.)/
* |hourly|: A /data block/ (see below) containing the weather
conditions hour-by-hour for the next two days.
* |daily|: A /data block/ (see below) containing the weather
conditions day-by-day for the next week.
* |alerts|: An array of /alert objects/ (see below), which, if
present, contains any severe weather alerts, issued by a
governmental weather authority, pertinent to the requested location.
* |flags|: An object containing miscellaneous metadata concerning this
request. (See /flags object/, below.)
In general, to determine the weather at a given point in time, one
should examine the highest-precision data block defined (|minutely|,
|hourly|, and |daily| respectively), taking any data available from from
it and falling back to the next-highest precision data block for any
properties that are missing for the point in time desired.
Data Points
A /data point/ object represents the various weather phenomena occurring
at a specific instant of time, and has many varied properties. All of
these properties (except |time|) are /optional/, and will only be set if
we have that type of information for that location and time. Please note
that |minutely| data points are always aligned to the nearest minute
boundary, |hourly| points to the top of the hour, and |daily| points to
midnight of that day.
Data points in the |daily| /data block/ (see below) are special: instead
of representing the weather phenomena at a given instant of time, they
are an aggregate point representing the weather phenomena that will
occur over the entire day. For precipitation fields, this aggregate is a
maximum; for other fields, it is an average.
Data point objects may contain the following properties:
* |time|: The UNIX time (that is, seconds since midnight GMT on 1 Jan
1970) at which this data point occurs.
* |summary|: A human-readable text summary of this data point.
* |icon|: A machine-readable text summary of this data point, suitable
for selecting an icon for display. If defined, this property will
have one of the following values: |clear-day|, |clear-night|,
|rain|, |snow|, |sleet|, |wind|, |fog|, |cloudy|,
|partly-cloudy-day|, or |partly-cloudy-night|. (Developers should
ensure that a sensible default is defined, as additional values,
such as |hail|, |thunderstorm|, or |tornado|, may be defined in the
future.)
* |sunriseTime| and |sunsetTime| (only defined on |daily| data
points): The UNIX time (that is, seconds since midnight GMT on 1 Jan
1970) of the last sunrise before and first sunset after the solar
noon closest to local noon on the given day. (Note: near the poles,
these may occur on a different day entirely!)
* |moonPhase| (only defined on |daily| data points): A number
representing the fractional part of the lunation number
<https://en.wikipedia.org/wiki/Lunation_Number> of the given day.
This can be thought of as the “percentage complete” of the current
lunar month: a value of |0| represents a new moon, a value of |0.25|
represents a first quarter moon, a value of |0.5| represents a full
moon, and a value of |0.75| represents a last quarter moon. (The
ranges in between these represent waxing crescent, waxing gibbous,
waning gibbous, and waning crescent moons, respectively.)
* |nearestStormDistance| (only defined on |currently| data points): A
numerical value representing the distance to the nearest storm in
miles. (This value is /very approximate/ and should not be used in
scenarios requiring accurate results. In particular, a storm
distance of zero doesn’t necessarily refer to a storm at the
requested location, but rather a storm in the vicinity of that
location.)
* |nearestStormBearing| (only defined on |currently| data points): A
numerical value representing the direction of the nearest storm in
degrees, with true north at 0° and progressing clockwise. (If
|nearestStormDistance| is zero, then this value will not be defined.
The caveats that apply to |nearestStormDistance| also apply to this
value.)
* |precipIntensity|: A numerical value representing the average
expected intensity (in inches of liquid water per hour) of
precipitation occurring at the given time /conditional on
probability/ (that is, assuming any precipitation occurs at all). A
/very/ rough guide is that a value of |0| in./hr. corresponds to no
precipitation, |0.002| in./hr. corresponds to very light
precipitation, |0.017| in./hr. corresponds to light precipitation,
|0.1| in./hr. corresponds to moderate precipitation, and |0.4|
in./hr. corresponds to heavy precipitation.
* |precipIntensityMax|, and |precipIntensityMaxTime| (only defined on
|daily| data points): numerical values representing the maximumum
expected intensity of precipitation (and the UNIX time at which it
occurs) on the given day in inches of liquid water per hour.
* |precipProbability|: A numerical value between 0 and 1 (inclusive)
representing the probability of precipitation occuring at the given
time.
* |precipType|: A string representing the type of precipitation
occurring at the given time. If defined, this property will have one
of the following values: |rain|, |snow|, |sleet| (which applies to
each of freezing rain, ice pellets, and “wintery mix”), or |hail|.
(If |precipIntensity| is zero, then this property will not be defined.)
* |precipAccumulation| (only defined on |hourly| and |daily| data
points): the amount of snowfall accumulation expected to occur on
the given day. (If no accumulation is expected, this property will
not be defined.)
* |temperature| (not defined on |daily| data points): A numerical
value representing the temperature at the given time in degrees
Fahrenheit.
* |temperatureMin|, |temperatureMinTime|, |temperatureMax|, and
|temperatureMaxTime| (only defined on |daily| data points):
numerical values representing the minimum and maximumum temperatures
(and the UNIX times at which they occur) on the given day in degrees
Fahrenheit.
* |apparentTemperature| (not defined on |daily| data points): A
numerical value representing the apparent (or “feels like”)
temperature at the given time in degrees Fahrenheit.
* |apparentTemperatureMin|, |apparentTemperatureMinTime|,
|apparentTemperatureMax|, and |apparentTemperatureMaxTime| (only
defined on |daily| data points): numerical values representing the
minimum and maximumum apparent temperatures (and the UNIX times at
which they occur) on the given day in degrees Fahrenheit.
* |dewPoint|: A numerical value representing the dew point at the
given time in degrees Fahrenheit.
* |windSpeed|: A numerical value representing the wind speed in miles
per hour.
* |windBearing|: A numerical value representing the direction that the
wind is coming /from/ in degrees, with true north at 0° and
progressing clockwise. (If |windSpeed| is zero, then this value will
not be defined.)
* |cloudCover|: A numerical value between 0 and 1 (inclusive)
representing the percentage of sky occluded by clouds. A value of
|0| corresponds to clear sky, |0.4| to scattered clouds, |0.75| to
broken cloud cover, and |1| to completely overcast skies.
* |humidity|: A numerical value between 0 and 1 (inclusive)
representing the relative humidity.
* |pressure|: A numerical value representing the sea-level air
pressure in millibars.
* |visibility|: A numerical value representing the average visibility
in miles, capped at 10 miles.
* |ozone|: A numerical value representing the columnar density of
total atmospheric ozone at the given time in Dobson units.
All of the above numeric, non-time fields may, optionally, have an
associated |Error| value defined (with the property
|precipIntensityError|, |windSpeedError|, |pressureError|, etc.),
representing our system’s confidence in its prediction. Such properties
represent standard deviations of the value of their associated property;
small error values therefore represent a strong confidence, while large
error values represent a weak confidence. These properties are omitted
where the confidence is not precisely known (though generally considered
to be adequate).
Data Blocks
A /data block/ object represents the various weather phenomena occurring
over a period of time. Such objects contain the following properties:
* |summary|: A human-readable text summary of this data block.
* |icon|: A machine-readable text summary of this data block (see
/data point/, above, for an enumeration of possible values that this
property may take on).
* |data|: An array of /data point/ objects (see above), ordered by
time, which together describe the weather conditions at the
requested location over time.
Ideally, the |minutely| data block will contain data for the next hour,
the |hourly| data block for the next two days, and the |daily| data
block for the next week; however, if we are lacking data for a given
time period, the data point sequence may contain gaps or terminate
early. Furthermore, if no data points for a time period are known, then
the data block will be omitted from the response in its entirety.
Developers are strongly encouraged, therefore, to check for the presence
of data before attempting to read it.
Alert Objects
An /alert object/ represents a severe weather warning issued for the
requested location by a governmental authority (for a list of which
authorities we currently support, please see /data sources/, below).
Such objects contain the following properties:
* |title|: A short text summary of the alert.
* |expires|: The UNIX time (that is, seconds since midnight GMT on 1
Jan 1970) at which the alert will cease to be valid.
* |description|: A detailed text description of the alert from the
appropriate weather service.
* |uri|: An HTTP(S) URI that contains detailed information about the
alert.
Flags Objects
The /flags object/ contains various metadata information related to the
request. Such objects may optionally contain any of the following
properties:
* |darksky-unavailable|: The presence of this property indicates that
the Dark Sky data source supports the given location, but a
temporary error (such as a radar station being down for maintenace)
has made the data unavailable.
* |darksky-stations|: This property contains an array of IDs for each
radar station utilized in servicing this request.
* |datapoint-stations|: This property contains an array of IDs for
each DataPoint station utilized in servicing this request.
* |isd-stations|: This property contains an array of IDs for each ISD
station utilized in servicing this request.
* |lamp-stations|: This property contains an array of IDs for each
LAMP station utilized in servicing this request.
* |metar-stations|: This property contains an array of IDs for each
METAR station utilized in servicing this request.
* |metno-license|: The presence of this property indicates that data
from api.met.no <http://api.met.no/> was utilized in order to
facilitate this request (as per their license agreement).
* |sources|: This property contains an array of IDs for each data
source utilized in servicing this request. (For more information,
see /data sources/, below.)
* |units|: The presence of this property indicates which units were
used for the data in this request. (For more information, see
/options/, below.)
Forecast at a Given Time
It is also possible to request a forecast for an arbitrary point in time:
|https://api.forecast.io/forecast/APIKEY/LATITUDE,LONGITUDE,TIME|
|TIME| should either be a UNIX time (that is, seconds since midnight GMT
on 1 Jan 1970) or a string formatted as follows:
|[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]| (with an optional time zone formatted
as |Z| for GMT time or |{+,-}[HH][MM]| for an offset in hours or
minutes). For the latter format, if no timezone is present, local time
(at the provided latitude and longitude) is assumed. (This string format
is a subset of ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations>
time. An as example, |2013-05-06T12:00:00-0400|.)
If a time is provided in this way, only the conditions for the day on
which that time occurred (or will occur), midnight-to-midnight, are
provided; in all other ways, making such a request is equivalent to
getting in a time machine, going back or forward in time to the given
moment, and making a normal forecast request. (In fact, this is how it
is implemented behind-the-scenes.) Generally speaking, forecasted data
is more accurate the nearer you query to the present moment. (That is,
the present moment if you don’t have a time machine.)
Options
The API request may optionally be modified through the use of query
parameters. It will respond to the following:
* |callback=[callback]|: Return the API response as JSONP
<https://en.wikipedia.org/wiki/JSONP>. /Please use caution when
using this,/ since exposing your API key to the public is a security
hazard and, if abused, will result in the revokation of your API
key. However, if developing a personal- or internal-use app, this is
a convenient method of doing so.
* |units=[setting]|: Return the API response in units other than the
default Imperial units. In particular, the following settings are
possible:
o |us|: The default, as outlined above.
o |si|: Returns results in SI units. In particular, properties now
have the following units:
+ |summary|: Any summaries containing temperature or snow
accumulation units will have their values in degrees Celsius
or in centimeters (respectively).
+ |nearestStormDistance|: Kilometers.
+ |precipIntensity|: Millimeters per hour.
+ |precipIntensityMax|: Millimeters per hour.
+ |precipAccumulation|: Centimeters.
+ |temperature|: Degrees Celsius.
+ |temperatureMin|: Degrees Celsius.
+ |temperatureMax|: Degrees Celsius.
+ |apparentTemperature|: Degrees Celsius.
+ |dewPoint|: Degrees Celsius.
+ |windSpeed|: Meters per second.
+ |pressure|: Hectopascals (which are, conveniently,
equivalent to the default millibars).
+ |visibility|: Kilometers.
o |ca|: Identical to |si|, except that |windSpeed| is in
kilometers per hour.
o |uk|: Identical to |si|, except that |windSpeed| is in miles per
hour, as in the US. (This option is provided because adoption of
SI in the UK has been inconsistent.)
o |auto|: Selects the relevant units automatically, based on
geographic location.
* |exclude=[blocks]|: Exclude some number of data blocks from the API
response. This is useful for reducing latency and saving cache
space. |[blocks]| should be a comma-delimeted list (without spaces)
of any of the following: |currently|, |minutely|, |hourly|, |daily|,
|alerts|, |flags|. (Crafting a request with /all/ of the above
blocks excluded is exceedingly silly and not recommended.)
* |extend=hourly|: When present on a forecast request, return hourly
data for the next seven days, rather than the next two. (This option
is ignored on time machine requests. When using this option, we
strongly recommend ensuring that your HTTP client supports compression.)
* |lang=[language]|: Return text summaries in the desired language.
(Please be advised that units in the summary will be set according
to the |units| option, above, so be sure to set both options as
needed.) |[language]| may be |bs| (Bosnian), |de| (German), |en|
(English, which is the default), |es| (Spanish), |fr| (French), |it|
(Italian), |nl| (Dutch), |pl| (Polish), |pt| (Portuguese), |ru|
(Russian), |tet| (Tetum), or |x-pig-latin| (Igpay Atinlay). (If a
different language is desired, please consider contributing to our
API translation module
<https://github.com/darkskyapp/forecast-io-translations> on Github.)
Response Headers
The API will set the following HTTP response headers to values useful to
developers:
* |Cache-Control| and |Expires|: These headers are set to conservative
values for data caching purposes based on the data present in the
response body.
* |X-Forecast-API-Calls|: The number of API calls made by the given
API key for today.
* |X-Response-Time|: The server-side response time of the request.
Notes
* Just about every object property in the response is optional. In
fact, a request with no data to return will return a nearly empty
object, rather than a failure. Robust code will check for the
presence of required parameters before using them, and will fail
gracefully if they are not present (or return an error if a minimum
functional set of data is not available).
* All numeric properties are real numbers, except for UNIX timestamps,
which are (signed) integers.
* Summaries on the |hourly| data block actually only cover up to a
maximum of 24 hours, rather than the full time period in the data
block. We found that covering the full 48 hours could be, in a
number of circumstances, far too wordy to be practical.
* Summaries and icons on |daily| data points actually cover the period
from 4AM to 4AM, rather than the stated time period of midnight to
midnight. We found that the summaries so generated were less awkward.
* The Forecast Data API supports HTTP compression. We heartily
recommend using it, as it will make responses much smaller over the
wire. To enable it, simply add an |Accept-Encoding: gzip| header to
your request. (Most HTTP client libraries wrap this functionality
for you, please consult your library’s documentation for details. Be
advised that we do not support such compression over HTTP/1.0
connections.)
* JSON responses are in UTF-8 format (due to text summaries, which can
contain Unicode characters). Please ensure that your JSON parser
acts accordingly.
Data Sources
This API is backed by a wide range of data sources, which are aggregated
together statistically to provide the most accurate forecast possible
for a given location. Any data sources used to service a given request
will be noted in the |flags| section of a forecast response. These
sources include:
1. Dark Sky’s own hyperlocal precipitation forecasting system
<http://journal.darkskyapp.com/2011/how-dark-sky-works/> (id
|darksky|), backed by radar data from the following systems:
* The USA NOAA’s NEXRAD system (USA).
* The UK Met Office’s NIMROD system (UK, Ireland).
* (More coming soon.)
2. The USA NOAA’s LAMP system
<http://www.nws.noaa.gov/mdl/lamp/index.shtml> (USA, id |lamp|).
3. The UK Met Office’s Datapoint API
<http://www.metoffice.gov.uk/datapoint> (UK, id |datapoint|).
4. The Norwegian Meteorological Institute’s meteorological forecast API
<http://api.met.no/> (global, id |metno|).
5. The USA NOAA’s Global Forecast System
<http://en.wikipedia.org/wiki/Global_Forecast_System> (global, id
|gfs|).
6. The USA NOAA’s Integrated Surface Database
<http://www.ncdc.noaa.gov/isd> (global, id |isd|).
7. The USA NOAA’s Public Alert system <http://alerts.weather.gov/>
(USA, id |nwspa|).
8. The UK Met Office’s Severe Weather Warning system
<http://www.metoffice.gov.uk/public/weather/warnings/> (UK, id
|metwarn|).
9. Environment Canada’s Canadian Meteorological Center ensemble model
<http://nomads.ncep.noaa.gov/txt_descriptions/CMCENS_doc.shtml>
(global, id |cmc|).
10. The US Navy’s Fleet Numerical Meteorology and Oceanography Ensemble
Forecast System
<http://nomads.ncep.noaa.gov/txt_descriptions/FENS_doc.shtml>
(global, id |fnmoc|).
11. The USA NOAA and Environment Canada’s North American Ensemble
Forecast System
<http://nomads.ncep.noaa.gov/txt_descriptions/NAEFS_bias_corrected_doc.shtml>
(global, id |naefs|).
12. The USA NOAA’s North American Mesoscale Model
<http://en.wikipedia.org/wiki/North_American_Mesoscale_Model> (North
America, id |nam|).
13. The USA NOAA’s Rapid Refresh Model <http://rapidrefresh.noaa.gov/>
(North America, id |rap|).
14. The Norwegian Meteorological Institute’s GRIB file forecast for
Central Europe
<http://api.met.no/weatherapi/gribfiles/1.0/documentation> (Europe,
id |metno_ce|).
15. The Norwegian Meteorological Institute’s GRIB file forecast for
Northern Europe
<http://api.met.no/weatherapi/gribfiles/1.0/documentation> (Europe,
id |metno_ne|).
16. Worldwide METAR weather reports <http://en.wikipedia.org/wiki/METAR>
(global, id |metar|).
17. The USA NOAA/NCEP’s Short-Range Ensemble Forecast
<http://www.emc.ncep.noaa.gov/mmb/SREF/SREF.html> (North America, id
|sref|).
18. The USA NOAA/NCEP’s Real-Time Mesoscale Analysis
<http://rapidrefresh.noaa.gov/> model (North America, id |rtma|).
19. The USA NOAA/ESRL’s Meteorological Assimilation Data Ingest System
<http://madis.noaa.gov/> (global, id |madis|).
v1-to-v2 Migration Guide
The v2 Forecast API is designed to be as close to a pure superset of the
v1 Forecast API <https://developer.darkskyapp.com/docs/forecast> as
possible, allowing for a straightforward upgrade path if you’re
currently using the v1 API and wish to upgrade. Below is a mapping of
all v1 response properties and how they map to v2 properties.
v1 Property v2 Property Notes
|timezone| |timezone| and |offset| In v1, |timezone| was a string
containing the IANA timezone name, the timezone abbrevation, and the
timezone offset in hours. In v2, |timezone| contains the IANA timezone
name, while |offset| contains the timezone offset in hours. The timezone
abbreviation has no analogue in v2.
|currentSummary| |currently.summary|
|currentIntensity| |currently.precipIntensity| In v1,
|currentIntensity| was in dBZ. In v2, |precipIntensity| is in inches of
liquid water per hour. An equation for converting between the two is
available from the Wikipedia page for dBZ
<https://en.wikipedia.org/wiki/DBZ_(meteorology)>.
|currentTemp| |currently.temperature|
|hourSummary| |minutely.summary|
|hourPrecipitation| |minutely.data| In v2, |minutely| may be omitted
entirely given a lack of data.
|hourPrecipitation[x].time| |minutely.data[x].time|
|hourPrecipitation[x].probability| |minutely.data[x].precipProbability|
|hourPrecipitation[x].intensity| |minutely.data[x].precipIntensity| In
v1, |intensity| was in dBZ. In v2, |precipIntensity| is in inches of
liquid water per hour. An equation for converting between the two is
available from the Wikipedia page for dBZ
<https://en.wikipedia.org/wiki/DBZ_(meteorology)>.
|hourPrecipitation[x].error| |minutely.data[x].precipIntensityError|
Note the change in |precipIntensity| units outlined above. Additionally,
in v2, this value is a one-sigma value rather than a three-sigma value,
and if |precipIntensity| is zero, then this property will be omitted
entirely.
|hourPrecipitation[x].type| |minutely.data[x].precipType| In v2, there
is an additional type of precipitation: |hail|. Additionally, in v2, if
|precipIntensity| is zero, then this property will be omitted.
|daySummary| |hourly.summary|
|dayPrecipitation| |hourly.data| In v2, |hourly| may be omitted
entirely given a lack of data.
|dayPrecipitation[x].time| |hourly.data[x].time|
|dayPrecipitation[x].probability| |hourly.data[x].precipProbability|
In v2, |precipProbability| will be omitted if |precipIntensity| is zero.
It is also very uncommonly provided by our data sources; developers are
encouraged to use rely on |precipIntensity| whenever possible.
|dayPrecipitation[x].type| |hourly.data[x].precipType| In v2, there is
an additional type of precipitation: |hail|. Additionally, in v2, if
|precipIntensity| is zero, then this property will be omitted.
|dayPrecipitation[x].temp| |hourly.data[x].temperature|
|dayPrecipitation[x].cloudCover| |hourly.data[x].cloudCover|
|dayPrecipitation[x].relHumidity| |hourly.data[x].humidity|
|radarStation| |flags["darksky-stations"]| In v2, this property will
be omitted if we do not have radar coverage of the given location.
Additionally, v2 makes use of multiple radar sources, so this property
contains an array of station IDs, rather than a single ID. Finally, in
v1, radar stations were lower case and would have their first letter
omitted if they began with a "K". In v2, radar station IDs are always
four letters long and upper case.
|isPrecipitating| /not present/ In v2, simply check if
|currently.precipIntensity| is nonzero.
|minutesUntilChange| /not present/ In v2, iterate over |minutely.data|
and |hourly.data| in order, finding the first data point for which
|currently.precipIntensity !== 0| does not equal
|datapoint.precipIntensity !== 0|. Once that data point is found,
|minutesUntilChange| may be calculated as follows: |(datapoint.time -
currently.time) / 60|.
|checkTimeout| /not present/ Use either the |Cache-Control| or
|Expires| HTTP response headers.
© 2013 The Dark Sky Company, LLC
Email Us <mailto:developer@forecast.io> Terms of Use </terms_of_use.txt>
Privacy Policy </privacy_policy.txt>