pastclimate 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +6 -0
- data/LICENSE +21 -0
- data/README.md +327 -0
- data/lib/pastclimate/client.rb +390 -0
- data/lib/pastclimate/errors.rb +139 -0
- data/lib/pastclimate/model.rb +88 -0
- data/lib/pastclimate/models.rb +406 -0
- data/lib/pastclimate/place.rb +75 -0
- data/lib/pastclimate/response.rb +125 -0
- data/lib/pastclimate/transport.rb +49 -0
- data/lib/pastclimate/version.rb +5 -0
- data/lib/pastclimate.rb +17 -0
- metadata +85 -0
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# Response models. Every field is optional on purpose: a field the server omits is nil,
|
|
4
|
+
# and a field this version does not know about is ignored (see Model#raw).
|
|
5
|
+
module PastClimate
|
|
6
|
+
# The point you asked for and how far it was from the grid cell that supplies the data.
|
|
7
|
+
class RequestedPoint < Model
|
|
8
|
+
# Latitude you asked for.
|
|
9
|
+
attribute :lat, :float
|
|
10
|
+
# Longitude you asked for.
|
|
11
|
+
attribute :lon, :float
|
|
12
|
+
# Great-circle distance from the requested point to the snapped grid cell, in km.
|
|
13
|
+
attribute :distance_km, :float
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
# Span of published data for a location's country.
|
|
17
|
+
class LocationCoverage < Model
|
|
18
|
+
# First year with published data for the country.
|
|
19
|
+
attribute :first_year, :integer
|
|
20
|
+
# Last day with published data for the country.
|
|
21
|
+
attribute :last_date, :date
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
# The place a response is about (the "location" part of the envelope).
|
|
25
|
+
class Location < Model
|
|
26
|
+
# Location id: country code, a slash, then the place slug. Use it as the location parameter.
|
|
27
|
+
attribute :id, :string
|
|
28
|
+
# Display name.
|
|
29
|
+
attribute :name, :string
|
|
30
|
+
# Lower-case two-letter country code.
|
|
31
|
+
attribute :country, :string
|
|
32
|
+
# Latitude of the centre of the grid cell that supplies the data (0.25 degree cells, about 28 km), not of the town centre.
|
|
33
|
+
attribute :lat, :float
|
|
34
|
+
# Longitude of the centre of the grid cell that supplies the data.
|
|
35
|
+
attribute :lon, :float
|
|
36
|
+
# IANA timezone. Daily and hourly days are local calendar days in this timezone.
|
|
37
|
+
attribute :timezone, :string
|
|
38
|
+
# Present only when the location was given as lat,lon (or by /v1/locations/nearest): the point that was snapped.
|
|
39
|
+
attribute :requested, RequestedPoint
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
# One result of a place search.
|
|
43
|
+
class LocationSearchResult < Model
|
|
44
|
+
# Location id.
|
|
45
|
+
attribute :id, :string
|
|
46
|
+
# Display name.
|
|
47
|
+
attribute :name, :string
|
|
48
|
+
# Lower-case two-letter country code.
|
|
49
|
+
attribute :country, :string
|
|
50
|
+
# Population, used to rank results.
|
|
51
|
+
attribute :population, :integer
|
|
52
|
+
# Grid cell centre latitude. Absent when weather_available is false.
|
|
53
|
+
attribute :lat, :float
|
|
54
|
+
# Grid cell centre longitude. Absent when weather_available is false.
|
|
55
|
+
attribute :lon, :float
|
|
56
|
+
# IANA timezone. Absent when weather_available is false.
|
|
57
|
+
attribute :timezone, :string
|
|
58
|
+
# false when this place cannot be served. Asking for its data returns 422 location_blocked.
|
|
59
|
+
attribute :weather_available, :boolean
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
# One location by id.
|
|
63
|
+
class LocationDetail < Model
|
|
64
|
+
# Location id.
|
|
65
|
+
attribute :id, :string
|
|
66
|
+
# Display name.
|
|
67
|
+
attribute :name, :string
|
|
68
|
+
# Lower-case two-letter country code.
|
|
69
|
+
attribute :country, :string
|
|
70
|
+
# Grid cell centre latitude.
|
|
71
|
+
attribute :lat, :float
|
|
72
|
+
# Grid cell centre longitude.
|
|
73
|
+
attribute :lon, :float
|
|
74
|
+
# IANA timezone.
|
|
75
|
+
attribute :timezone, :string
|
|
76
|
+
# Population.
|
|
77
|
+
attribute :population, :integer
|
|
78
|
+
attribute :coverage, LocationCoverage
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
# The place nearest a point.
|
|
82
|
+
class NearestLocation < Model
|
|
83
|
+
# Location id.
|
|
84
|
+
attribute :id, :string
|
|
85
|
+
# Display name.
|
|
86
|
+
attribute :name, :string
|
|
87
|
+
# Lower-case two-letter country code.
|
|
88
|
+
attribute :country, :string
|
|
89
|
+
# Grid cell centre latitude.
|
|
90
|
+
attribute :lat, :float
|
|
91
|
+
# Grid cell centre longitude.
|
|
92
|
+
attribute :lon, :float
|
|
93
|
+
# IANA timezone.
|
|
94
|
+
attribute :timezone, :string
|
|
95
|
+
# Present only when the location was given as lat,lon (or by /v1/locations/nearest): the point that was snapped.
|
|
96
|
+
attribute :requested, RequestedPoint
|
|
97
|
+
# Population.
|
|
98
|
+
attribute :population, :integer
|
|
99
|
+
end
|
|
100
|
+
|
|
101
|
+
# One local calendar day of weather.
|
|
102
|
+
class DailyRow < Model
|
|
103
|
+
# The local calendar day, in the location's timezone.
|
|
104
|
+
attribute :date, :date
|
|
105
|
+
# Mean temperature of the day, deg C. With units=imperial: deg F.
|
|
106
|
+
attribute :daily_avg_temp, :float
|
|
107
|
+
# Lowest temperature of the day, deg C. With units=imperial: deg F.
|
|
108
|
+
attribute :daily_min_temp, :float
|
|
109
|
+
# Highest temperature of the day, deg C. With units=imperial: deg F.
|
|
110
|
+
attribute :daily_max_temp, :float
|
|
111
|
+
# Total precipitation of the day, mm. With units=imperial: inches.
|
|
112
|
+
attribute :daily_total_rain, :float
|
|
113
|
+
# Mean wind speed of the day, m/s. With units=imperial: mph.
|
|
114
|
+
attribute :daily_avg_wind, :float
|
|
115
|
+
# Mean cloud cover of the day, 0 to 100.
|
|
116
|
+
attribute :daily_avg_cloud_percent, :integer
|
|
117
|
+
# true when total precipitation was at least 1 mm.
|
|
118
|
+
attribute :rain_flag, :boolean
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
# One hour of weather.
|
|
122
|
+
class HourlyRow < Model
|
|
123
|
+
# Start of the hour, UTC.
|
|
124
|
+
attribute :timestamp_utc, :time
|
|
125
|
+
# Air temperature at 2 m, deg C. With units=imperial: deg F.
|
|
126
|
+
attribute :temperature, :float
|
|
127
|
+
# Apparent temperature (Steadman), deg C. With units=imperial: deg F.
|
|
128
|
+
attribute :feels_like_temperature, :float
|
|
129
|
+
# Dewpoint, deg C. With units=imperial: deg F.
|
|
130
|
+
attribute :dewpoint, :float
|
|
131
|
+
# Precipitation in the hour, mm. With units=imperial: inches.
|
|
132
|
+
attribute :precipitation, :float
|
|
133
|
+
# Wind speed, m/s. With units=imperial: mph.
|
|
134
|
+
attribute :wind_speed, :float
|
|
135
|
+
# Wind direction, degrees, 0 to 360.
|
|
136
|
+
attribute :wind_direction_deg, :float
|
|
137
|
+
# Relative humidity, 0 to 100, derived from temperature and dewpoint.
|
|
138
|
+
attribute :relative_humidity_percent, :float
|
|
139
|
+
# Surface pressure, hPa. With units=imperial: inHg.
|
|
140
|
+
attribute :pressure, :float
|
|
141
|
+
# Total cloud cover, 0 to 100.
|
|
142
|
+
attribute :cloud_cover_percent, :integer
|
|
143
|
+
# Solar radiation received in the hour, kWh per square metre. Not changed by units.
|
|
144
|
+
attribute :solar_radiation_kwh_m2, :float
|
|
145
|
+
end
|
|
146
|
+
|
|
147
|
+
# One calendar month (UTC) of summary values.
|
|
148
|
+
class MonthlyRow < Model
|
|
149
|
+
# Calendar year (UTC).
|
|
150
|
+
attribute :year, :integer
|
|
151
|
+
# Month, 1 to 12 (UTC).
|
|
152
|
+
attribute :month, :integer
|
|
153
|
+
# Mean hourly temperature, deg C. With units=imperial: deg F.
|
|
154
|
+
attribute :monthly_avg_temp, :float
|
|
155
|
+
# Lowest hourly temperature in the month, deg C. With units=imperial: deg F.
|
|
156
|
+
attribute :monthly_min_temp, :float
|
|
157
|
+
# Highest hourly temperature in the month, deg C. With units=imperial: deg F.
|
|
158
|
+
attribute :monthly_max_temp, :float
|
|
159
|
+
# Total precipitation, mm. With units=imperial: inches.
|
|
160
|
+
attribute :monthly_total_rain, :float
|
|
161
|
+
# Mean wind speed, m/s. With units=imperial: mph.
|
|
162
|
+
attribute :monthly_avg_wind, :float
|
|
163
|
+
# Mean surface pressure, hPa. With units=imperial: inHg.
|
|
164
|
+
attribute :monthly_avg_pressure, :float
|
|
165
|
+
# Mean cloud cover, 0 to 100.
|
|
166
|
+
attribute :monthly_avg_cloud_percent, :float
|
|
167
|
+
# Total solar radiation, joules per square metre. Not changed by units.
|
|
168
|
+
attribute :monthly_total_solar_j_m2, :float
|
|
169
|
+
# Days with at least 1 mm of precipitation.
|
|
170
|
+
attribute :rainy_days, :integer
|
|
171
|
+
# Days with at least 20 mm of precipitation.
|
|
172
|
+
attribute :heavy_rain_days, :integer
|
|
173
|
+
# Days with a maximum of at least 40 deg C. A count, not changed by units.
|
|
174
|
+
attribute :extreme_heat_days, :integer
|
|
175
|
+
# Days with a minimum of at most 0 deg C. A count, not changed by units.
|
|
176
|
+
attribute :extreme_cold_days, :integer
|
|
177
|
+
# Hourly values that went into the month.
|
|
178
|
+
attribute :hours, :integer
|
|
179
|
+
# Days that went into the day counts.
|
|
180
|
+
attribute :days, :integer
|
|
181
|
+
end
|
|
182
|
+
|
|
183
|
+
# One calendar year (UTC) of summary values.
|
|
184
|
+
class YearlyRow < Model
|
|
185
|
+
# Calendar year (UTC).
|
|
186
|
+
attribute :year, :integer
|
|
187
|
+
# Mean hourly temperature, deg C. With units=imperial: deg F.
|
|
188
|
+
attribute :yearly_avg_temp, :float
|
|
189
|
+
# Lowest hourly temperature in the year, deg C. With units=imperial: deg F.
|
|
190
|
+
attribute :yearly_min_temp, :float
|
|
191
|
+
# Highest hourly temperature in the year, deg C. With units=imperial: deg F.
|
|
192
|
+
attribute :yearly_max_temp, :float
|
|
193
|
+
# Total precipitation, mm. With units=imperial: inches.
|
|
194
|
+
attribute :yearly_total_rain, :float
|
|
195
|
+
# Mean wind speed, m/s. With units=imperial: mph.
|
|
196
|
+
attribute :yearly_avg_wind, :float
|
|
197
|
+
# Mean surface pressure, hPa. With units=imperial: inHg.
|
|
198
|
+
attribute :yearly_avg_pressure, :float
|
|
199
|
+
# Mean cloud cover, 0 to 100.
|
|
200
|
+
attribute :yearly_avg_cloud_percent, :float
|
|
201
|
+
# Total solar radiation, joules per square metre. Not changed by units.
|
|
202
|
+
attribute :yearly_total_solar_j_m2, :float
|
|
203
|
+
# Days with at least 1 mm of precipitation.
|
|
204
|
+
attribute :rainy_days, :integer
|
|
205
|
+
# Days with at least 20 mm of precipitation.
|
|
206
|
+
attribute :heavy_rain_days, :integer
|
|
207
|
+
# Days with a maximum of at least 40 deg C.
|
|
208
|
+
attribute :extreme_heat_days, :integer
|
|
209
|
+
# Days with a minimum of at most 0 deg C.
|
|
210
|
+
attribute :extreme_cold_days, :integer
|
|
211
|
+
# Hourly values that went into the year.
|
|
212
|
+
attribute :hours, :integer
|
|
213
|
+
# Days that went into the day counts.
|
|
214
|
+
attribute :days, :integer
|
|
215
|
+
# Months that went into the year (12 for a complete year).
|
|
216
|
+
attribute :months, :integer
|
|
217
|
+
end
|
|
218
|
+
|
|
219
|
+
# Climate normal for one month.
|
|
220
|
+
class NormalsMonthlyRow < Model
|
|
221
|
+
# Month, 1 to 12.
|
|
222
|
+
attribute :month, :integer
|
|
223
|
+
# Mean daily mean temperature, deg C. With units=imperial: deg F.
|
|
224
|
+
attribute :avg_temp, :float
|
|
225
|
+
# Mean daily minimum temperature, deg C. With units=imperial: deg F.
|
|
226
|
+
attribute :min_temp, :float
|
|
227
|
+
# Mean daily maximum temperature, deg C. With units=imperial: deg F.
|
|
228
|
+
attribute :max_temp, :float
|
|
229
|
+
# Mean monthly precipitation total, mm. With units=imperial: inches.
|
|
230
|
+
attribute :total_rain, :float
|
|
231
|
+
# Mean number of days with at least 1 mm of precipitation.
|
|
232
|
+
attribute :rainy_days, :float
|
|
233
|
+
# Mean wind speed, m/s. With units=imperial: mph.
|
|
234
|
+
attribute :avg_wind, :float
|
|
235
|
+
# Mean cloud cover, 0 to 100.
|
|
236
|
+
attribute :avg_cloud_pct, :float
|
|
237
|
+
# Mean daily solar radiation, kWh per square metre. Not changed by units.
|
|
238
|
+
attribute :avg_solar_kwh_m2, :float
|
|
239
|
+
# Years of data the normal is averaged over.
|
|
240
|
+
attribute :years_covered, :integer
|
|
241
|
+
# Mean relative humidity, 0 to 100.
|
|
242
|
+
attribute :avg_humidity_pct, :float
|
|
243
|
+
end
|
|
244
|
+
|
|
245
|
+
# Climate normal for one calendar day of the year.
|
|
246
|
+
class NormalsDayRow < Model
|
|
247
|
+
# Calendar day as MM-DD. 02-29 is included.
|
|
248
|
+
attribute :md, :string
|
|
249
|
+
# Mean daily mean temperature on this calendar day, deg C. With units=imperial: deg F.
|
|
250
|
+
attribute :avg_temp, :float
|
|
251
|
+
# Mean daily minimum, deg C. With units=imperial: deg F.
|
|
252
|
+
attribute :min_temp, :float
|
|
253
|
+
# Mean daily maximum, deg C. With units=imperial: deg F.
|
|
254
|
+
attribute :max_temp, :float
|
|
255
|
+
# Share of years, 0 to 1, with at least 1 mm of precipitation on this calendar day.
|
|
256
|
+
attribute :rain_prob, :float
|
|
257
|
+
end
|
|
258
|
+
|
|
259
|
+
# Monthly and day-of-year climate normals.
|
|
260
|
+
class NormalsData < Model
|
|
261
|
+
# 12 rows, or 1 when month is given.
|
|
262
|
+
attribute :monthly, [NormalsMonthlyRow]
|
|
263
|
+
# 366 rows, or the days of that month when month is given.
|
|
264
|
+
attribute :day_of_year, [NormalsDayRow]
|
|
265
|
+
end
|
|
266
|
+
|
|
267
|
+
# One extreme on record.
|
|
268
|
+
class RecordItem < Model
|
|
269
|
+
# Which extreme.
|
|
270
|
+
attribute :metric, :string
|
|
271
|
+
# The extreme value, in the unit given by unit.
|
|
272
|
+
attribute :value, :float
|
|
273
|
+
# Unit of value.
|
|
274
|
+
attribute :unit, :string
|
|
275
|
+
# The day the extreme occurred.
|
|
276
|
+
attribute :occurred_on, :date
|
|
277
|
+
end
|
|
278
|
+
|
|
279
|
+
# The plan of the account the key belongs to.
|
|
280
|
+
class MePlan < Model
|
|
281
|
+
# Plan id.
|
|
282
|
+
attribute :id, :string
|
|
283
|
+
# Plan name.
|
|
284
|
+
attribute :name, :string
|
|
285
|
+
# Whether commercial use is allowed.
|
|
286
|
+
attribute :commercial_use, :boolean
|
|
287
|
+
# Whether a visible link back is required.
|
|
288
|
+
attribute :attribution_link_required, :boolean
|
|
289
|
+
# Most days one /v1/hourly call may ask for.
|
|
290
|
+
attribute :hourly_max_days_per_call, :integer
|
|
291
|
+
# How far back hourly data goes, in months. null for full history.
|
|
292
|
+
attribute :hourly_max_age_months, :integer
|
|
293
|
+
end
|
|
294
|
+
|
|
295
|
+
# The key the call was made with.
|
|
296
|
+
class MeKey < Model
|
|
297
|
+
# Which credits this key spends first: "plan_first" or "topup_first".
|
|
298
|
+
attribute :spend_order, :string
|
|
299
|
+
end
|
|
300
|
+
|
|
301
|
+
# Credit balance and usage.
|
|
302
|
+
class MeCredits < Model
|
|
303
|
+
# One-time credits for the life of the account. They never refill. null when your plan has none.
|
|
304
|
+
attribute :one_time_limit, :integer
|
|
305
|
+
# One-time credits left. null when your plan has none.
|
|
306
|
+
attribute :one_time_remaining, :integer
|
|
307
|
+
# Credits used since the account was created, on any plan.
|
|
308
|
+
attribute :used_all_time, :integer
|
|
309
|
+
# Credits in your plan each month. null when your plan has no monthly credits.
|
|
310
|
+
attribute :monthly_limit, :integer
|
|
311
|
+
# Credits used this month (UTC).
|
|
312
|
+
attribute :used_this_month, :integer
|
|
313
|
+
# Credits left this month. null when your plan has no monthly credits.
|
|
314
|
+
attribute :remaining_this_month, :integer
|
|
315
|
+
# When the monthly allowance next renews (UTC). null when your plan has no monthly allowance.
|
|
316
|
+
attribute :month_resets_at, :time
|
|
317
|
+
# Most credits you can use in a day. null when there is no daily credit cap.
|
|
318
|
+
attribute :daily_cap, :integer
|
|
319
|
+
# Credits used today (UTC).
|
|
320
|
+
attribute :used_today, :integer
|
|
321
|
+
# Credits left today. null when there is no daily credit cap.
|
|
322
|
+
attribute :remaining_today, :integer
|
|
323
|
+
# When the daily count resets.
|
|
324
|
+
attribute :day_resets_at, :time
|
|
325
|
+
# Bought credits left. They never expire and never reset. Calls spend your plan's credits first, then these.
|
|
326
|
+
attribute :topup_balance, :integer
|
|
327
|
+
# Bought credits spent so far.
|
|
328
|
+
attribute :topup_used, :integer
|
|
329
|
+
end
|
|
330
|
+
|
|
331
|
+
# Per-minute request limit.
|
|
332
|
+
class MeRateLimit < Model
|
|
333
|
+
# Requests allowed per minute.
|
|
334
|
+
attribute :per_minute, :integer
|
|
335
|
+
# Requests left in the current minute.
|
|
336
|
+
attribute :remaining, :integer
|
|
337
|
+
end
|
|
338
|
+
|
|
339
|
+
# Your plan, credit balance and limits.
|
|
340
|
+
class MeData < Model
|
|
341
|
+
attribute :plan, MePlan
|
|
342
|
+
attribute :key, MeKey
|
|
343
|
+
attribute :credits, MeCredits
|
|
344
|
+
attribute :rate_limit, MeRateLimit
|
|
345
|
+
end
|
|
346
|
+
|
|
347
|
+
# Published coverage of one country.
|
|
348
|
+
class CountryCoverage < Model
|
|
349
|
+
# Lower-case two-letter country code.
|
|
350
|
+
attribute :country, :string
|
|
351
|
+
# First year with published data.
|
|
352
|
+
attribute :first_year, :integer
|
|
353
|
+
# Last day with published data.
|
|
354
|
+
attribute :last_date, :date
|
|
355
|
+
end
|
|
356
|
+
|
|
357
|
+
# The countries the archive serves.
|
|
358
|
+
class CoverageData < Model
|
|
359
|
+
attribute :countries, [CountryCoverage]
|
|
360
|
+
end
|
|
361
|
+
|
|
362
|
+
# The unit system used for the values in a response.
|
|
363
|
+
class MetaUnits < Model
|
|
364
|
+
# The unit system used for the values in this response.
|
|
365
|
+
attribute :system, :string
|
|
366
|
+
# Temperature unit.
|
|
367
|
+
attribute :temperature, :string
|
|
368
|
+
# Precipitation unit.
|
|
369
|
+
attribute :precipitation, :string
|
|
370
|
+
# Wind speed unit.
|
|
371
|
+
attribute :wind_speed, :string
|
|
372
|
+
# Pressure unit.
|
|
373
|
+
attribute :pressure, :string
|
|
374
|
+
end
|
|
375
|
+
|
|
376
|
+
# Response metadata: credits used and left, plus the fields each endpoint adds. Fields an endpoint does not send are null.
|
|
377
|
+
class Meta < Model
|
|
378
|
+
# Credits this call used. 0 on an error.
|
|
379
|
+
attribute :credits, :integer
|
|
380
|
+
# Credits the next call can spend: the plan's remaining allowance plus bought credits.
|
|
381
|
+
attribute :credits_remaining, :integer
|
|
382
|
+
# Version of the data-processing methodology. Changes only when published numbers can shift.
|
|
383
|
+
attribute :methodology_version, :string
|
|
384
|
+
# The search text.
|
|
385
|
+
attribute :query, :string
|
|
386
|
+
# The country filter, or null.
|
|
387
|
+
attribute :country, :string
|
|
388
|
+
# Results returned.
|
|
389
|
+
attribute :count, :integer
|
|
390
|
+
attribute :units, MetaUnits
|
|
391
|
+
# First day.
|
|
392
|
+
attribute :start, :date
|
|
393
|
+
# Last day.
|
|
394
|
+
attribute :end, :date
|
|
395
|
+
# Rows returned.
|
|
396
|
+
attribute :days, :integer
|
|
397
|
+
# First day.
|
|
398
|
+
attribute :date, :date
|
|
399
|
+
# Timezone of the local days.
|
|
400
|
+
attribute :timezone, :string
|
|
401
|
+
# Rows returned.
|
|
402
|
+
attribute :rows, :integer
|
|
403
|
+
# The month filter, or null.
|
|
404
|
+
attribute :month, :integer
|
|
405
|
+
end
|
|
406
|
+
end
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module PastClimate
|
|
4
|
+
# Where to get weather for: a location id, or a latitude/longitude plus country.
|
|
5
|
+
#
|
|
6
|
+
# PastClimate::Place.id("gb/london")
|
|
7
|
+
# PastClimate::Place.point(lat: 51.5, lon: -0.12, country: "gb")
|
|
8
|
+
#
|
|
9
|
+
# Anywhere a place is expected you may also pass the id as a plain String.
|
|
10
|
+
# A point is snapped to the nearest place in that country; the server echoes
|
|
11
|
+
# the snapped point in +response.location.requested+.
|
|
12
|
+
class Place
|
|
13
|
+
POINT_LIKE = /\A\s*-?\d+(\.\d+)?\s*,\s*-?\d+(\.\d+)?\s*\z/.freeze
|
|
14
|
+
|
|
15
|
+
attr_reader :location, :country
|
|
16
|
+
|
|
17
|
+
def self.id(id)
|
|
18
|
+
text = id.to_s.strip
|
|
19
|
+
raise ArgumentError, "a location id is required, for example \"gb/london\"" if text.empty?
|
|
20
|
+
if text.match?(POINT_LIKE)
|
|
21
|
+
raise ArgumentError, "#{text.inspect} looks like a point; use Place.point(lat:, lon:, country:)"
|
|
22
|
+
end
|
|
23
|
+
|
|
24
|
+
new(text, nil)
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
def self.point(lat:, lon:, country:)
|
|
28
|
+
raise ArgumentError, "lat and lon must be numbers" unless finite_number?(lat) && finite_number?(lon)
|
|
29
|
+
|
|
30
|
+
cc = country.to_s.strip
|
|
31
|
+
raise ArgumentError, "country is required with a lat/lon point, for example \"gb\"" if cc.empty?
|
|
32
|
+
|
|
33
|
+
new("#{format_number(lat)},#{format_number(lon)}", cc)
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# Turns a String id or a Place into a Place.
|
|
37
|
+
def self.coerce(value)
|
|
38
|
+
case value
|
|
39
|
+
when Place then value
|
|
40
|
+
when String then id(value)
|
|
41
|
+
else raise ArgumentError, "expected a location id String or a PastClimate::Place, got #{value.class}"
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def self.finite_number?(value)
|
|
46
|
+
value.is_a?(Numeric) && value.to_f.finite?
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Plain decimal text, never scientific notation.
|
|
50
|
+
def self.format_number(value)
|
|
51
|
+
format("%.10f", value.to_f).sub(/0+\z/, "").sub(/\.\z/, "")
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def initialize(location, country)
|
|
55
|
+
@location = location
|
|
56
|
+
@country = country
|
|
57
|
+
freeze
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# Query parameters for this place.
|
|
61
|
+
def to_query
|
|
62
|
+
params = { "location" => location }
|
|
63
|
+
params["country"] = country if country
|
|
64
|
+
params
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def to_s
|
|
68
|
+
country ? "#{location} (#{country})" : location
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
def inspect
|
|
72
|
+
"#<PastClimate::Place #{self}>"
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
end
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module PastClimate
|
|
4
|
+
# Helpers for reading response headers (names are lower-cased).
|
|
5
|
+
module Headers
|
|
6
|
+
def self.normalize(headers)
|
|
7
|
+
result = {}
|
|
8
|
+
(headers || {}).each { |name, value| result[name.to_s.downcase] = value.is_a?(Array) ? value.join(", ") : value.to_s }
|
|
9
|
+
result
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
# An integer header, or nil when it is absent or not a whole number.
|
|
13
|
+
def self.integer(headers, name)
|
|
14
|
+
value = headers[name]
|
|
15
|
+
return nil if value.nil?
|
|
16
|
+
|
|
17
|
+
text = value.to_s.strip
|
|
18
|
+
text.match?(/\A\d+\z/) ? text.to_i : nil
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# Retry-After in whole seconds, or nil. Only the delay-in-seconds form is read.
|
|
22
|
+
def self.retry_after(headers)
|
|
23
|
+
integer(headers, "retry-after")
|
|
24
|
+
end
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
# The per-minute request limit as the server reported it. Any value is nil
|
|
28
|
+
# when the response did not carry that header (some refusals do not).
|
|
29
|
+
class RateLimit
|
|
30
|
+
attr_reader :limit, :remaining, :reset
|
|
31
|
+
|
|
32
|
+
def initialize(limit: nil, remaining: nil, reset: nil)
|
|
33
|
+
@limit = limit
|
|
34
|
+
@remaining = remaining
|
|
35
|
+
@reset = reset
|
|
36
|
+
freeze
|
|
37
|
+
end
|
|
38
|
+
|
|
39
|
+
def self.from_headers(headers)
|
|
40
|
+
new(
|
|
41
|
+
limit: Headers.integer(headers, "ratelimit-limit"),
|
|
42
|
+
remaining: Headers.integer(headers, "ratelimit-remaining"),
|
|
43
|
+
reset: Headers.integer(headers, "ratelimit-reset")
|
|
44
|
+
)
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
def to_h
|
|
48
|
+
{ limit: limit, remaining: remaining, reset: reset }
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def ==(other)
|
|
52
|
+
other.is_a?(RateLimit) && to_h == other.to_h
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
def inspect
|
|
56
|
+
"#<PastClimate::RateLimit limit=#{limit.inspect} remaining=#{remaining.inspect} reset=#{reset.inspect}>"
|
|
57
|
+
end
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
# What every call has in common: HTTP status, headers, the rate limit and the
|
|
61
|
+
# credit numbers.
|
|
62
|
+
module ResponseInfo
|
|
63
|
+
attr_reader :status, :headers, :rate_limit
|
|
64
|
+
|
|
65
|
+
# Credits this call used (meta.credits, else the X-Credits-Used header), or nil.
|
|
66
|
+
def credits_used
|
|
67
|
+
from_meta = meta&.credits
|
|
68
|
+
from_meta.nil? ? Headers.integer(headers, "x-credits-used") : from_meta
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
# Credits you can still spend (meta.credits_remaining, else the
|
|
72
|
+
# X-Credits-Remaining header), or nil.
|
|
73
|
+
def credits_remaining
|
|
74
|
+
from_meta = meta&.credits_remaining
|
|
75
|
+
from_meta.nil? ? Headers.integer(headers, "x-credits-remaining") : from_meta
|
|
76
|
+
end
|
|
77
|
+
|
|
78
|
+
def meta
|
|
79
|
+
nil
|
|
80
|
+
end
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# A JSON answer: +data+ (typed models), +location+, +meta+, plus rate-limit and credit info.
|
|
84
|
+
class Response
|
|
85
|
+
include ResponseInfo
|
|
86
|
+
|
|
87
|
+
attr_reader :data, :location, :meta
|
|
88
|
+
|
|
89
|
+
def initialize(data:, location:, meta:, status:, headers:)
|
|
90
|
+
@data = data
|
|
91
|
+
@location = location
|
|
92
|
+
@meta = meta
|
|
93
|
+
@status = status
|
|
94
|
+
@headers = headers
|
|
95
|
+
@rate_limit = RateLimit.from_headers(headers)
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
def inspect
|
|
99
|
+
"#<PastClimate::Response status=#{status} credits_used=#{credits_used.inspect} credits_remaining=#{credits_remaining.inspect}>"
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
# A CSV answer (+format: :csv+). +csv+ is the text. There is no meta in a CSV
|
|
104
|
+
# body, so credit numbers come from the response headers.
|
|
105
|
+
class CsvResponse
|
|
106
|
+
include ResponseInfo
|
|
107
|
+
|
|
108
|
+
attr_reader :csv
|
|
109
|
+
|
|
110
|
+
def initialize(csv:, status:, headers:)
|
|
111
|
+
@csv = csv
|
|
112
|
+
@status = status
|
|
113
|
+
@headers = headers
|
|
114
|
+
@rate_limit = RateLimit.from_headers(headers)
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
def to_s
|
|
118
|
+
csv
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
def inspect
|
|
122
|
+
"#<PastClimate::CsvResponse status=#{status} bytes=#{csv.bytesize} credits_used=#{credits_used.inspect}>"
|
|
123
|
+
end
|
|
124
|
+
end
|
|
125
|
+
end
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "net/http"
|
|
4
|
+
require "openssl"
|
|
5
|
+
require "uri"
|
|
6
|
+
|
|
7
|
+
module PastClimate
|
|
8
|
+
# What a transport returns: HTTP status, lower-cased header names, body text.
|
|
9
|
+
TransportResponse = Struct.new(:status, :headers, :body, keyword_init: true)
|
|
10
|
+
|
|
11
|
+
# The default transport, built on Net::HTTP. A transport is any object with
|
|
12
|
+
#
|
|
13
|
+
# call(method:, url:, headers:, timeout:) -> TransportResponse
|
|
14
|
+
#
|
|
15
|
+
# that raises PastClimate::ConnectionError when no HTTP answer arrives. Pass
|
|
16
|
+
# your own to Client.new(transport: ...) to use another HTTP library or a fake.
|
|
17
|
+
class NetHttpTransport
|
|
18
|
+
NETWORK_ERRORS = [
|
|
19
|
+
SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
|
|
20
|
+
Net::HTTPBadResponse, Net::ProtocolError
|
|
21
|
+
].freeze
|
|
22
|
+
|
|
23
|
+
def call(method:, url:, headers:, timeout:)
|
|
24
|
+
raise ArgumentError, "only GET is supported" unless method == :get
|
|
25
|
+
|
|
26
|
+
uri = URI.parse(url)
|
|
27
|
+
http = Net::HTTP.new(uri.host, uri.port)
|
|
28
|
+
http.use_ssl = uri.scheme == "https"
|
|
29
|
+
http.open_timeout = timeout
|
|
30
|
+
http.read_timeout = timeout
|
|
31
|
+
http.write_timeout = timeout
|
|
32
|
+
http.max_retries = 0 # the client does its own retrying
|
|
33
|
+
request = Net::HTTP::Get.new(uri.request_uri, headers)
|
|
34
|
+
response = http.start { |connection| connection.request(request) }
|
|
35
|
+
|
|
36
|
+
response_headers = {}
|
|
37
|
+
response.each_header { |name, value| response_headers[name.downcase] = value }
|
|
38
|
+
TransportResponse.new(
|
|
39
|
+
status: response.code.to_i,
|
|
40
|
+
headers: response_headers,
|
|
41
|
+
body: response.body.to_s.dup.force_encoding(Encoding::UTF_8)
|
|
42
|
+
)
|
|
43
|
+
rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
|
|
44
|
+
raise ConnectionError.new("The request timed out (#{e.class}).", timeout: true)
|
|
45
|
+
rescue *NETWORK_ERRORS => e
|
|
46
|
+
raise ConnectionError, "Network error: #{e.class}: #{e.message}"
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
end
|
data/lib/pastclimate.rb
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "pastclimate/version"
|
|
4
|
+
require "pastclimate/response"
|
|
5
|
+
require "pastclimate/errors"
|
|
6
|
+
require "pastclimate/model"
|
|
7
|
+
require "pastclimate/models"
|
|
8
|
+
require "pastclimate/place"
|
|
9
|
+
require "pastclimate/transport"
|
|
10
|
+
require "pastclimate/client"
|
|
11
|
+
|
|
12
|
+
# Official Ruby client for the PastClimate historical weather API.
|
|
13
|
+
#
|
|
14
|
+
# client = PastClimate::Client.new # reads PASTCLIMATE_API_KEY
|
|
15
|
+
# client.get_me.data.plan.name
|
|
16
|
+
module PastClimate
|
|
17
|
+
end
|