|
1 | | -# 🚗 `vehiclesdb` – Official Ruby SDK for the VehiclesDB API |
| 1 | +# `vehiclesdb` — official alias of [`vehicles`](https://github.com/vehiclesdb/vehicles) |
2 | 2 |
|
3 | | -[](https://badge.fury.io/rb/vehiclesdb) [](https://github.com/rameerez/vehiclesdb-ruby/actions) |
4 | | - |
5 | | -> [!TIP] |
6 | | -> **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=vehiclesdb)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=vehiclesdb)! |
7 | | -
|
8 | | -`vehiclesdb` is the official Ruby client for the [**VehiclesDB API**](https://vehiclesdb.com) — a hosted service for rich vehicle data: production years, model images (year- and color-accurate), market segments, specifications, and more. |
9 | | - |
10 | | -> [!NOTE] |
11 | | -> **This is an early shell release.** It reserves the gem and sets its shape; the VehiclesDB API isn't public yet, so resource methods (models, images, …) land as the service ships. Configuration, the client, and the error model are in place today. |
12 | | -
|
13 | | -## `vehiclesdb` vs `vehicles` — which do I want? |
14 | | - |
15 | | -Two gems, one product, and they're **fully independent** (each works on its own): |
16 | | - |
17 | | -| | [`vehicles`](https://github.com/rameerez/vehicles) | `vehiclesdb` (this gem) | |
18 | | -|---|---|---| |
19 | | -| What | Bundled make/model dataset + a delightful local API | Thin client for the hosted VehiclesDB API | |
20 | | -| Data | Ships **inside the gem** (EU, offline) | Lives on the **server** (the paid API) | |
21 | | -| Setup | Zero — no key, no network | Needs an API key | |
22 | | -| Use it for | Make/model dropdowns, search, validation | Years, images, segments, specs | |
23 | | - |
24 | | -Most apps want **`vehicles`** — it works offline with zero config. Add **`vehiclesdb`** (and a key) when you want the richer hosted data; `vehicles` will use it automatically for enrichment. Or use `vehiclesdb` directly if all you want is the raw API. |
25 | | - |
26 | | -## Installation |
| 3 | +This gem is a two-file front door: it depends on |
| 4 | +[**`vehicles`**](https://github.com/vehiclesdb/vehicles) — the Ruby SDK for |
| 5 | +the [VehiclesDB](https://github.com/vehiclesdb/vehiclesdb) open vehicle |
| 6 | +dataset — and exposes the identical API under the `VehiclesDB` constant. |
27 | 7 |
|
28 | 8 | ```ruby |
29 | 9 | gem "vehiclesdb" |
30 | 10 | ``` |
31 | 11 |
|
32 | | -## Usage |
33 | | - |
34 | 12 | ```ruby |
35 | | -VehiclesDB.configure do |config| |
36 | | - config.api_key = ENV["VEHICLESDB_API_KEY"] # or just set ENV["VEHICLESDB_API_KEY"] |
37 | | -end |
38 | | - |
39 | | -VehiclesDB.client.configured? # => true |
| 13 | +VehiclesDB.find("vw golf") # => #<Vehicles::Model "Volkswagen Golf"> |
| 14 | +VehiclesDB.top_models(kind: :motorcycle, country: :th, limit: 5) |
| 15 | +VehiclesDB.equal?(Vehicles) # => true — same module, two names |
40 | 16 | ``` |
41 | 17 |
|
42 | | -You can also build a client explicitly (handy for multiple keys / standalone use): |
43 | | - |
44 | | -```ruby |
45 | | -client = VehiclesDB::Client.new(api_key: "vdb_live_...") |
46 | | -client.configured? # => true |
47 | | -``` |
48 | | - |
49 | | -### Errors |
50 | | - |
51 | | -Everything raises a subclass of `VehiclesDB::Error`, so you can rescue broadly or narrowly: |
52 | | - |
53 | | -```ruby |
54 | | -VehiclesDB::Error # rescue-all base |
55 | | -VehiclesDB::ConfigurationError # no API key configured |
56 | | -VehiclesDB::AuthenticationError # bad key (HTTP 401/403) |
57 | | -VehiclesDB::ApiError # other non-2xx — carries #status and #body |
58 | | -``` |
59 | | - |
60 | | -## Configuration |
61 | | - |
62 | | -| Option | Default | Notes | |
63 | | -|---|---|---| |
64 | | -| `api_key` | `ENV["VEHICLESDB_API_KEY"]` | your VehiclesDB key | |
65 | | -| `api_base_url` | `https://api.vehiclesdb.com` | override for staging/self-host/tests | |
66 | | -| `timeout` | `5` | request timeout (seconds) | |
67 | | -| `user_agent` | `vehiclesdb-ruby/<version>` | sent with every request | |
68 | | - |
69 | | -## Development |
70 | | - |
71 | | -After checking out the repo, run `bin/setup` to install dependencies. Then run |
72 | | -`rake test`. You can also run `bin/console` for an interactive prompt. |
73 | | - |
74 | | -To install this gem onto your local machine, run `bundle exec rake install`. |
75 | | - |
76 | | -## Contributing |
77 | | - |
78 | | -Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/vehiclesdb-ruby. Our code of conduct is: just be nice and make your mom proud of what you do and post online. |
| 18 | +**Why two names?** The project is bigger than Ruby: the dataset lives at |
| 19 | +[github.com/vehiclesdb/vehiclesdb](https://github.com/vehiclesdb/vehiclesdb) |
| 20 | +and SDKs for other languages follow the `vehiclesdb-<language>` pattern. If |
| 21 | +you found the project through that name, this gem takes you to the right |
| 22 | +place. If you're starting fresh in Ruby, depend on |
| 23 | +[`vehicles`](https://github.com/vehiclesdb/vehicles) directly — it's the |
| 24 | +same thing with the shorter, Rails-idiomatic name. |
79 | 25 |
|
80 | | -## License |
| 26 | +Docs, features, dataset details: **see the |
| 27 | +[`vehicles` README](https://github.com/vehiclesdb/vehicles#readme)**. |
81 | 28 |
|
82 | | -The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). |
| 29 | +Code MIT · bundled data CC-BY 4.0 (VehiclesDB). |
0 commit comments