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 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
@@ -0,0 +1,6 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+
5
+ First release. One method per API operation, typed responses and errors,
6
+ automatic retries, CSV for daily and hourly data.
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).