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
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: cfc7716584a677611790489d9ef756e0b4e30e043fb2609108331d6af8922466
|
|
4
|
+
data.tar.gz: 903f6c943b1f31004d33e2c53100affff788c9677ce7a95d2e91105762360e6a
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 28034e963decf562b8ca602bfa048bd98ed1861557c84f973f68ebd6952f15bd44d888be7a405eeaaee88b3f296709352a4a05d2ed03da5e30ffa23d833b8f23
|
|
7
|
+
data.tar.gz: f07101c69e05a74f36aa548648d5e85103a4282926215163aead0d9147e880e6080d303c73c900ad6df7c43c3b0f281a5d613bb88dea8580ed2c7fcd09bb8a78
|
data/CHANGELOG.md
ADDED
data/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PastClimate
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
# pastclimate (Ruby)
|
|
2
|
+
|
|
3
|
+
The official Ruby client for the [PastClimate API](https://developer.pastclimate.com/api/):
|
|
4
|
+
historical daily, hourly, monthly and yearly weather, climate normals and records.
|
|
5
|
+
|
|
6
|
+
- Ruby 3.0 or newer. No runtime dependencies (it uses `net/http`).
|
|
7
|
+
- One method per API operation, with typed response models.
|
|
8
|
+
- One error class per kind of failure.
|
|
9
|
+
- Automatic retries where retrying is safe.
|
|
10
|
+
- Credit and rate-limit numbers on every response.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
gem install pastclimate
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
or in your `Gemfile`:
|
|
19
|
+
|
|
20
|
+
```ruby
|
|
21
|
+
gem "pastclimate"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Quickstart
|
|
25
|
+
|
|
26
|
+
Get a key on your [API page](https://www.pastclimate.com/account/api/) and put it in an
|
|
27
|
+
environment variable. Never put a key in source code or in a URL.
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
export PASTCLIMATE_API_KEY=your_key_here
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```ruby
|
|
34
|
+
require "pastclimate"
|
|
35
|
+
|
|
36
|
+
client = PastClimate::Client.new # reads PASTCLIMATE_API_KEY
|
|
37
|
+
|
|
38
|
+
response = client.get_daily("gb/london", start_date: "2024-01-01", end_date: "2024-01-31")
|
|
39
|
+
|
|
40
|
+
response.data.each do |day|
|
|
41
|
+
puts "#{day.date}: #{day.daily_min_temp} to #{day.daily_max_temp}"
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
puts "Used #{response.credits_used} credits, #{response.credits_remaining} left"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
A runnable version is in [`examples/quickstart.rb`](examples/quickstart.rb). It makes real calls, so it
|
|
48
|
+
only runs when `PASTCLIMATE_API_KEY` is set.
|
|
49
|
+
|
|
50
|
+
## Configuration
|
|
51
|
+
|
|
52
|
+
```ruby
|
|
53
|
+
client = PastClimate::Client.new(
|
|
54
|
+
api_key: "...", # default: ENV["PASTCLIMATE_API_KEY"]
|
|
55
|
+
base_url: "https://api.pastclimate.com", # default: ENV["PASTCLIMATE_BASE_URL"], then this value
|
|
56
|
+
timeout: 30, # seconds per attempt
|
|
57
|
+
max_retries: 2, # retries after the first try
|
|
58
|
+
max_retry_delay: 60 # longest wait the client will sleep between tries
|
|
59
|
+
)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- With no key, `Client.new` raises `PastClimate::ConfigurationError`.
|
|
63
|
+
- `base_url` must be `https`. Plain `http` is accepted only for `localhost` and `127.0.0.1`.
|
|
64
|
+
- The key is sent as `Authorization: Bearer <key>`, never in the URL. `client.inspect` hides it.
|
|
65
|
+
- Redirects are not followed, so the key cannot be sent to another host.
|
|
66
|
+
- The `User-Agent` is `pastclimate-ruby/<version>`.
|
|
67
|
+
|
|
68
|
+
## Places
|
|
69
|
+
|
|
70
|
+
Every weather method takes a place as its first argument. Give it in one of two ways.
|
|
71
|
+
|
|
72
|
+
```ruby
|
|
73
|
+
# 1. A location id: country code, slash, place slug. A plain String works.
|
|
74
|
+
client.get_monthly("gb/london")
|
|
75
|
+
client.get_monthly(PastClimate::Place.id("gb/london"))
|
|
76
|
+
|
|
77
|
+
# 2. A latitude and longitude, with the two-letter country they are in.
|
|
78
|
+
point = PastClimate::Place.point(lat: 51.5, lon: -0.12, country: "gb")
|
|
79
|
+
client.get_monthly(point)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Find ids with `search_locations`. A point is snapped to the nearest place in that country; the
|
|
83
|
+
response's `location.requested` shows the point you sent and how far away the chosen place is.
|
|
84
|
+
|
|
85
|
+
## Methods
|
|
86
|
+
|
|
87
|
+
Every method returns a `PastClimate::Response` with `data`, `location`, `meta`, `rate_limit`,
|
|
88
|
+
`credits_used`, `credits_remaining`, `status` and `headers`. The type of `data` is given below.
|
|
89
|
+
Fields the server leaves out are `nil`; fields this version does not know about are ignored
|
|
90
|
+
(`model.raw` has the original hash).
|
|
91
|
+
|
|
92
|
+
Dates are `Date` objects and timestamps are UTC `Time` objects. You may pass dates as `Date`,
|
|
93
|
+
`Time` or `"YYYY-MM-DD"` strings.
|
|
94
|
+
|
|
95
|
+
### `search_locations(q, country: nil)`
|
|
96
|
+
|
|
97
|
+
Search places by the start of their name. `data` is an `Array` of `LocationSearchResult`.
|
|
98
|
+
|
|
99
|
+
```ruby
|
|
100
|
+
found = client.search_locations("lon", country: "gb")
|
|
101
|
+
found.data.each { |place| puts "#{place.id} #{place.name} #{place.weather_available}" }
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### `nearest_location(lat:, lon:, country:)`
|
|
105
|
+
|
|
106
|
+
The place nearest a point, inside one country. `data` is a `NearestLocation`.
|
|
107
|
+
|
|
108
|
+
```ruby
|
|
109
|
+
nearest = client.nearest_location(lat: 51.5, lon: -0.12, country: "gb")
|
|
110
|
+
puts "#{nearest.data.id}, #{nearest.data.requested.distance_km} km away"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### `get_location(id)`
|
|
114
|
+
|
|
115
|
+
One location by id. `data` is a `LocationDetail`, including `coverage` (`first_year`, `last_date`).
|
|
116
|
+
|
|
117
|
+
```ruby
|
|
118
|
+
london = client.get_location("gb/london")
|
|
119
|
+
puts london.data.timezone, london.data.coverage.last_date
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### `get_daily(location, start_date:, end_date:, units: nil, format: :json)`
|
|
123
|
+
|
|
124
|
+
Daily values from `start_date` to `end_date`, both included. `data` is an `Array` of `DailyRow`.
|
|
125
|
+
|
|
126
|
+
```ruby
|
|
127
|
+
daily = client.get_daily("gb/london", start_date: "2024-01-01", end_date: "2024-01-31", units: :imperial)
|
|
128
|
+
daily.data.each { |d| puts "#{d.date} #{d.daily_avg_temp} #{daily.meta.units.temperature}" }
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### `get_hourly(location, date:, days: nil, units: nil, format: :json)`
|
|
132
|
+
|
|
133
|
+
Hourly values for `days` consecutive local days starting at `date`. `data` is an `Array` of `HourlyRow`.
|
|
134
|
+
Leave `days` out for the server default.
|
|
135
|
+
|
|
136
|
+
```ruby
|
|
137
|
+
hourly = client.get_hourly("gb/london", date: "2024-01-15", days: 1)
|
|
138
|
+
hourly.data.each { |h| puts "#{h.timestamp_utc.iso8601} #{h.temperature}" }
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### `get_monthly(location, units: nil)`
|
|
142
|
+
|
|
143
|
+
Every month on file. `data` is an `Array` of `MonthlyRow`.
|
|
144
|
+
|
|
145
|
+
```ruby
|
|
146
|
+
monthly = client.get_monthly("gb/london")
|
|
147
|
+
puts monthly.data.last.monthly_total_rain
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### `get_yearly(location, units: nil)`
|
|
151
|
+
|
|
152
|
+
Every year on file. `data` is an `Array` of `YearlyRow`.
|
|
153
|
+
|
|
154
|
+
```ruby
|
|
155
|
+
yearly = client.get_yearly("gb/london")
|
|
156
|
+
yearly.data.each { |y| puts "#{y.year} #{y.yearly_avg_temp}" }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### `get_normals(location, month: nil, units: nil)`
|
|
160
|
+
|
|
161
|
+
Climate normals. `data` is a `NormalsData` with `monthly` and `day_of_year` arrays. `month:` (1 to 12)
|
|
162
|
+
narrows both to one month.
|
|
163
|
+
|
|
164
|
+
```ruby
|
|
165
|
+
normals = client.get_normals("gb/london", month: 7)
|
|
166
|
+
puts normals.data.monthly.first.avg_temp
|
|
167
|
+
puts normals.data.day_of_year.first.rain_prob
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### `get_records(location, units: nil)`
|
|
171
|
+
|
|
172
|
+
The hottest, coldest, wettest and windiest day on file. `data` is an `Array` of `RecordItem`.
|
|
173
|
+
|
|
174
|
+
```ruby
|
|
175
|
+
client.get_records("gb/london").data.each do |record|
|
|
176
|
+
puts "#{record.metric}: #{record.value} #{record.unit} on #{record.occurred_on}"
|
|
177
|
+
end
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### `get_coverage(country: nil)`
|
|
181
|
+
|
|
182
|
+
The countries the archive serves, and the first year and last day of published data for each.
|
|
183
|
+
`data` is a `CoverageData`. Check it before asking for dates near the end of the archive.
|
|
184
|
+
|
|
185
|
+
```ruby
|
|
186
|
+
client.get_coverage(country: "gb").data.countries.each do |c|
|
|
187
|
+
puts "#{c.country}: #{c.first_year} to #{c.last_date}"
|
|
188
|
+
end
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### `get_me`
|
|
192
|
+
|
|
193
|
+
Your plan, credit balance and limits. `data` is a `MeData`. Use it instead of hard-coding limits.
|
|
194
|
+
|
|
195
|
+
```ruby
|
|
196
|
+
me = client.get_me.data
|
|
197
|
+
puts me.plan.name
|
|
198
|
+
puts me.credits.used_this_month
|
|
199
|
+
puts me.rate_limit.per_minute
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Units
|
|
203
|
+
|
|
204
|
+
`units:` is `:metric` (the server default) or `:imperial`. Field names are the same in both; the
|
|
205
|
+
unit of each value is in `response.meta.units` (`system`, `temperature`, `precipitation`,
|
|
206
|
+
`wind_speed`, `pressure`). Anything else raises `ArgumentError` before a request is sent.
|
|
207
|
+
|
|
208
|
+
```ruby
|
|
209
|
+
response = client.get_records("gb/london", units: :imperial)
|
|
210
|
+
puts response.meta.units.temperature # => "F"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## CSV
|
|
214
|
+
|
|
215
|
+
`get_daily` and `get_hourly` can return CSV. Pass `format: :csv`, or use the shorthands
|
|
216
|
+
`get_daily_csv` and `get_hourly_csv`. You get a `PastClimate::CsvResponse`:
|
|
217
|
+
|
|
218
|
+
```ruby
|
|
219
|
+
csv = client.get_daily_csv("gb/london", start_date: "2023-01-01", end_date: "2023-12-31")
|
|
220
|
+
File.write("london-2023.csv", csv.csv)
|
|
221
|
+
puts csv.credits_used
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
A CSV body has no `meta`, so `credits_used`, `credits_remaining` and `rate_limit` come from the
|
|
225
|
+
response headers. If the request fails you still get a typed error, never an error saved as CSV.
|
|
226
|
+
|
|
227
|
+
## Credits and rate limits
|
|
228
|
+
|
|
229
|
+
Every response, JSON or CSV, tells you what the call cost and what is left:
|
|
230
|
+
|
|
231
|
+
```ruby
|
|
232
|
+
response = client.get_monthly("gb/london")
|
|
233
|
+
|
|
234
|
+
response.credits_used # credits this call used
|
|
235
|
+
response.credits_remaining # credits you can still spend (may be nil)
|
|
236
|
+
response.meta.methodology_version
|
|
237
|
+
|
|
238
|
+
limit = response.rate_limit # the per-minute request limit
|
|
239
|
+
limit.limit # requests allowed per minute
|
|
240
|
+
limit.remaining # requests left in this minute
|
|
241
|
+
limit.reset # seconds until the oldest request leaves the minute window
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
The SDK does not know what a call costs and does not check your balance. Read the numbers from the
|
|
245
|
+
response, or call `get_me`. Rate-limit values are `nil` when the server did not send the header.
|
|
246
|
+
|
|
247
|
+
## Errors
|
|
248
|
+
|
|
249
|
+
Every failure is a subclass of `PastClimate::Error`.
|
|
250
|
+
|
|
251
|
+
| Class | Raised for (error `code`) |
|
|
252
|
+
|---|---|
|
|
253
|
+
| `AuthenticationError` | `missing_key`, `invalid_key`, `key_revoked`, `email_not_verified`, `account_suspended` |
|
|
254
|
+
| `InvalidRequestError` | `invalid_request`, `range_too_large`, `key_in_query`, `cors_not_supported`, `method_not_allowed` |
|
|
255
|
+
| `NotFoundError` | `location_not_found`, `not_published`, `not_found`, `location_blocked` |
|
|
256
|
+
| `PlanRequiredError` | `plan_required` |
|
|
257
|
+
| `RateLimitedError` | `rate_limited`, `daily_request_cap_reached` |
|
|
258
|
+
| `QuotaExceededError` | `quota_exceeded` |
|
|
259
|
+
| `ServerError` | `internal_error`, `api_disabled`, `metering_unavailable` (and `invalid_response`, when a success body cannot be read) |
|
|
260
|
+
| `ConnectionError` | no HTTP answer: DNS, TLS, reset or timeout (`error.timeout?`) |
|
|
261
|
+
| `ConfigurationError` | the client was set up wrongly |
|
|
262
|
+
|
|
263
|
+
The first seven (`AuthenticationError` to `ServerError`) inherit from `PastClimate::ApiError` and carry
|
|
264
|
+
`status`, `code`, `message`, `docs_url`, plus `headers`, `rate_limit`, `retry_after` (seconds, or `nil`),
|
|
265
|
+
`upgrade_url` and the raw `body`. An unknown future code still maps to a class by its HTTP status. If a
|
|
266
|
+
proxy answers without the API's error body, `code` is `"http_<status>"` and `docs_url` is `nil`.
|
|
267
|
+
|
|
268
|
+
```ruby
|
|
269
|
+
begin
|
|
270
|
+
client.get_daily("gb/london", start_date: "1900-01-01", end_date: "1900-01-31")
|
|
271
|
+
rescue PastClimate::NotFoundError => e
|
|
272
|
+
puts "No data: #{e.code} - #{e.message}" # e.g. not_published; see client.get_coverage
|
|
273
|
+
rescue PastClimate::QuotaExceededError => e
|
|
274
|
+
puts "Out of credits. Upgrade: #{e.upgrade_url}"
|
|
275
|
+
rescue PastClimate::RateLimitedError => e
|
|
276
|
+
puts "Slow down. Wait #{e.retry_after.inspect} seconds."
|
|
277
|
+
rescue PastClimate::ApiError => e
|
|
278
|
+
puts "#{e.status} #{e.code}: #{e.message} (#{e.docs_url})"
|
|
279
|
+
rescue PastClimate::ConnectionError => e
|
|
280
|
+
puts "Network problem: #{e.message}"
|
|
281
|
+
end
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Branch on the class or `code`, not on the message. Failed calls are not charged.
|
|
285
|
+
|
|
286
|
+
## Retries
|
|
287
|
+
|
|
288
|
+
The client retries a call automatically, up to `max_retries` times (default 2):
|
|
289
|
+
|
|
290
|
+
| Failure | What happens |
|
|
291
|
+
|---|---|
|
|
292
|
+
| `429` **with** `Retry-After` | waits that many seconds, then retries |
|
|
293
|
+
| `429` **without** `Retry-After` | raised at once (on a plan with one-time credits this means they are used up, and waiting does not help) |
|
|
294
|
+
| `500`, `502`, `503`, any `5xx` | retries with exponential backoff and jitter |
|
|
295
|
+
| network error or timeout | retries with the same backoff |
|
|
296
|
+
| any other `4xx` | raised at once; fix the request |
|
|
297
|
+
|
|
298
|
+
A `429` whose `Retry-After` is longer than `max_retry_delay` (default 60 seconds), for example "wait
|
|
299
|
+
until midnight UTC", is raised instead of slept on; `retry_after` tells you how long. Set
|
|
300
|
+
`max_retries: 0` to turn retrying off. Retries repeat the same GET, so they cannot double-send
|
|
301
|
+
anything. Refused calls still count toward your daily request limit, so do not wrap the client in an
|
|
302
|
+
unbounded retry loop of your own.
|
|
303
|
+
|
|
304
|
+
## Custom HTTP transport
|
|
305
|
+
|
|
306
|
+
The default transport uses `Net::HTTP`. To use another library, or a fake in your own tests, pass any
|
|
307
|
+
object with `call(method:, url:, headers:, timeout:)` that returns a `PastClimate::TransportResponse`
|
|
308
|
+
(`status`, `headers` with lower-case names, `body`) and raises `PastClimate::ConnectionError` when no
|
|
309
|
+
HTTP answer arrives:
|
|
310
|
+
|
|
311
|
+
```ruby
|
|
312
|
+
client = PastClimate::Client.new(api_key: "test", transport: MyTransport.new)
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
## Development
|
|
316
|
+
|
|
317
|
+
```sh
|
|
318
|
+
bundle install
|
|
319
|
+
bundle exec rake test
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Without Bundler: `ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require File.expand_path(f) }'`.
|
|
323
|
+
The tests use a fake transport and a small local HTTP server; they never call the real API.
|
|
324
|
+
|
|
325
|
+
## License
|
|
326
|
+
|
|
327
|
+
MIT. See [LICENSE](LICENSE).
|