diff --git a/README.md b/README.md index 803c680..ebf763d 100644 --- a/README.md +++ b/README.md @@ -19,22 +19,47 @@ The Dark Sky API requires an API key. See the [Dark Sky Developer Documentation] ```julia # DarkSky.jl is not currently registered as an official package # Please install the development version from GitHub: -Pkg.clone("git://github.com:ellisvalentiner/DarkSky.jl.git") +Pkg.clone("git://github.com/ellisvalentiner/DarkSky.jl.git") ``` DarkSky.jl expects your API key to be stored as an environment variable named `DARKSKY_API_KEY`. ## Usage +The basic usage is to request the current weather forecast (a [Forecast Request](https://darksky.net/dev/docs#forecast-request)) or the observed or forecast weather conditions for a datetime in the past or future (a [Time Machine Request](https://darksky.net/dev/docs#time-machine-request)). + ```julia using DarkSky # Make a "Forecast Request", returns the current weather forecast for the next week. -forecast(42.3601, -71.0589) +response = forecast(42.3601, -71.0589); # Make a "Time Machine Request", returns the observed or forecast weather conditions for a date in # the past or future. -forecast(42.3601, -71.0589, DateTime(2018, 3, 7, 14, 19, 57)) +response = forecast(42.3601, -71.0589, DateTime(2018, 3, 7, 14, 19, 57)); ``` +The Dark Sky response contains the following properties (and can be accessed by functions with the same name): + +* `latitude` - The requested latitude. +* `longitude` - The requested longitude. +* `timezone` - The IANA timezone name for the requested location. +* `currently` - A data point containing the current weather conditions at the requested location. (optional) +* `minutely` - A data block containing the weather conditions minute-by-minute for the next hour. (optional) +* `hourly` - A data block containing the weather conditions hour-by-hour for the next two days. (optional) +* `daily` - A data block containing the weather conditions day-by-day for the next week. (optional) +* `alerts` - An alerts array, which, if present, contains any severe weather alerts pertinent to the requested location. (optional) +* `flags` - A flags object containing miscellaneous metadata about the request. (optional) + +```julia +# Extract the requested latitude +latitude(response) +# Extract the "daily" data block +daily(response) +# Extract the "alerts" data block +alerts(response) +``` + +Note that optional properties may not contain data (e.g. there may be no alerts). + ## Contributing See the [CONTRIBUTING](https://github.com/ellisvalentiner/DarkSky.jl/blob/master/CONTRIBUTING) file. diff --git a/src/DarkSky.jl b/src/DarkSky.jl index 3c15eb2..9fa2923 100644 --- a/src/DarkSky.jl +++ b/src/DarkSky.jl @@ -27,6 +27,18 @@ struct DarkSkyResponse end DarkSkyResponse(x::Dict) = DarkSkyResponse((get.(x, String.(fieldnames(DarkSkyResponse)), nothing))...) +function Base.show(io::IO, x::DarkSkyResponse) + print(io, (x.latitude, x.longitude), "\n" * x.daily["summary"]) +end + +for fieldname in fieldnames(DarkSkyResponse) + fname = Symbol(fieldname) + @eval begin + ($fieldname)(x::DarkSkyResponse) = x.$fname + export $fieldname + end +end + function _get_json(url::String, verbose::Bool) response = HTTP.get(url) verbose ? info(response) : nothing