auto-api-client 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 93857c52418aed8a134ae9db8cb1c190452640c4628ab7763e64f385ac0d43d9
+  data.tar.gz: 3947a3e3b025d391ac3880efb732683b9d03e19678a20cb43707fc51e4b916b2
+SHA512:
+  metadata.gz: 805daa1befec1aeb8155cbfeb623c4588603f293056dbc489d447cef084fa48afa9c0699b16c8d8361bc1262bdd257c77c50c996c8b731831990ffd038e294c4
+  data.tar.gz: 125f2750890bb0e4c2f9d70fc8e812a14587e0744109c225faeb3fdc63d72d638f7d9b4ae55d71aa75bb75c7a3afba56490a77631e552fa1ab69cee1f499b7e3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AUTO-API.COM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# auto-api-client-ruby
+
+[![Gem Version](https://badge.fury.io/rb/auto-api-client.svg)](https://rubygems.org/gems/auto-api-client)
+[![Ruby](https://img.shields.io/badge/Ruby-2.5%2B-red)](https://ruby-lang.org)
+[![License](https://img.shields.io/github/license/autoapicom/auto-api-ruby)](LICENSE)
+
+Ruby gem for the [auto-api.com](https://auto-api.com) car listings API — 8 marketplaces, one client.
+
+encar, mobile.de, autoscout24, che168, dongchedi, guazi, dubicars, dubizzle. No dependencies beyond stdlib (`net/http` + `json`).
+
+## Installation
+
+```bash
+gem install auto-api-client
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "auto-api-client"
+```
+
+## Usage
+
+```ruby
+require "auto_api"
+
+client = AutoApi::Client.new("your-api-key")
+```
+
+### Get filters
+
+```ruby
+filters = client.get_filters("encar")
+```
+
+### Search offers
+
+```ruby
+offers = client.get_offers("mobilede", page: 1, brand: "BMW", year_from: 2020)
+
+# Pagination
+puts offers["meta"]["page"]
+puts offers["meta"]["next_page"]
+```
+
+### Get single offer
+
+```ruby
+offer = client.get_offer("encar", "40427050")
+```
+
+### Track changes
+
+```ruby
+change_id = client.get_change_id("encar", "2025-01-15")
+changes = client.get_changes("encar", change_id)
+
+# Next batch
+next_batch = client.get_changes("encar", changes["meta"]["next_change_id"])
+```
+
+### Get offer by URL
+
+```ruby
+info = client.get_offer_by_url("https://encar.com/dc/dc_cardetailview.do?carid=40427050")
+```
+
+### Decode offer data
+
+The `data` hash structure depends on the source — each marketplace has its own set of fields:
+
+```ruby
+offers["result"].each do |item|
+  data = item["data"]
+  puts "#{data['mark']} #{data['model']} #{data['year']} — $#{data['price']}"
+end
+```
+
+### Error handling
+
+```ruby
+begin
+  offers = client.get_offers("encar", page: 1)
+rescue AutoApi::AuthError => e
+  # 401/403 — invalid API key
+  puts "#{e.status_code}: #{e.message}"
+rescue AutoApi::ApiError => e
+  # Any other API error
+  puts "#{e.status_code}: #{e.message}"
+  puts e.response_body
+end
+```
+
+## Supported sources
+
+| Source | Platform | Region |
+|--------|----------|--------|
+| `encar` | [encar.com](https://encar.com) | South Korea |
+| `mobilede` | [mobile.de](https://mobile.de) | Germany |
+| `autoscout24` | [autoscout24.com](https://autoscout24.com) | Europe |
+| `che168` | [che168.com](https://che168.com) | China |
+| `dongchedi` | [dongchedi.com](https://dongchedi.com) | China |
+| `guazi` | [guazi.com](https://guazi.com) | China |
+| `dubicars` | [dubicars.com](https://dubicars.com) | UAE |
+| `dubizzle` | [dubizzle.com](https://dubizzle.com) | UAE |
+
+## Other languages
+
+| Language | Package |
+|----------|---------|
+| PHP | [auto-api/client](https://github.com/autoapicom/auto-api-php) |
+| TypeScript | [@auto-api/client](https://github.com/autoapicom/auto-api-node) |
+| Python | [auto-api-client](https://github.com/autoapicom/auto-api-python) |
+| Go | [auto-api-go](https://github.com/autoapicom/auto-api-go) |
+| C# | [AutoApi.Client](https://github.com/autoapicom/auto-api-dotnet) |
+| Java | [auto-api-client](https://github.com/autoapicom/auto-api-java) |
+| Rust | [auto-api-client](https://github.com/autoapicom/auto-api-rust) |
+
+## Documentation
+
+[auto-api.com](https://auto-api.com)

data/lib/auto_api/client.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module AutoApi
+  # Client for the auto-api.com car listings API.
+  class Client
+    # Creates a new API client.
+    #
+    # @param api_key [String] API key from auto-api.com
+    # @param api_version [String] API version (default: "v2")
+    # @param base_url [String] base URL override (default: "https://auto-api.com")
+    def initialize(api_key, api_version: "v2", base_url: "https://auto-api.com")
+      @api_key = api_key
+      @api_version = api_version
+      @base_url = base_url.chomp("/")
+    end
+
+    # Returns available filters for a source (brands, models, body types, etc.)
+    #
+    # @param source [String] source platform name
+    # @return [Hash] available filters
+    def get_filters(source)
+      get("api/#{@api_version}/#{source}/filters")
+    end
+
+    # Returns a paginated list of offers with optional filters.
+    #
+    # @param source [String] source platform name
+    # @param params [Hash] query parameters (page, brand, model, etc.)
+    # @return [Hash] { "result" => [...], "meta" => { "page" => ..., "next_page" => ... } }
+    def get_offers(source, params = {})
+      get("api/#{@api_version}/#{source}/offers", params)
+    end
+
+    # Returns a single offer by inner_id.
+    #
+    # @param source [String] source platform name
+    # @param inner_id [String] offer inner ID
+    # @return [Hash] offer data
+    def get_offer(source, inner_id)
+      get("api/#{@api_version}/#{source}/offer", { inner_id: inner_id })
+    end
+
+    # Returns a change_id for the given date.
+    #
+    # @param source [String] source platform name
+    # @param date [String] date in yyyy-mm-dd format
+    # @return [Integer] change_id for the given date
+    def get_change_id(source, date)
+      result = get("api/#{@api_version}/#{source}/change_id", { date: date })
+      result["change_id"]
+    end
+
+    # Returns a changes feed (added/changed/removed) starting from change_id.
+    #
+    # @param source [String] source platform name
+    # @param change_id [Integer] change ID to start from
+    # @return [Hash] { "result" => [...], "meta" => { "cur_change_id" => ..., "next_change_id" => ... } }
+    def get_changes(source, change_id)
+      get("api/#{@api_version}/#{source}/changes", { change_id: change_id })
+    end
+
+    # Returns offer data by its URL on the marketplace.
+    # Uses POST /api/v1/offer/info with x-api-key header.
+    #
+    # @param url [String] marketplace offer URL
+    # @return [Hash] offer data
+    def get_offer_by_url(url)
+      post("api/v1/offer/info", { url: url })
+    end
+
+    private
+
+    def get(endpoint, params = {})
+      params[:api_key] = @api_key
+
+      uri = URI("#{@base_url}/#{endpoint}")
+      uri.query = URI.encode_www_form(params)
+
+      request = Net::HTTP::Get.new(uri)
+      execute(uri, request)
+    end
+
+    def post(endpoint, data)
+      uri = URI("#{@base_url}/#{endpoint}")
+
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["x-api-key"] = @api_key
+      request.body = JSON.generate(data)
+
+      execute(uri, request)
+    end
+
+    def execute(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 30
+      http.read_timeout = 30
+
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    def handle_response(response)
+      body = response.body
+      status_code = response.code.to_i
+
+      unless (200...300).include?(status_code)
+        message = "API error: #{status_code}"
+
+        begin
+          parsed = JSON.parse(body)
+          message = parsed["message"] if parsed.is_a?(Hash) && parsed["message"]
+        rescue JSON::ParserError
+          # Use default message if response is not valid JSON
+        end
+
+        if status_code == 401 || status_code == 403
+          raise AuthError.new(status_code, message, body)
+        end
+
+        raise ApiError.new(status_code, message, body)
+      end
+
+      begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise ApiError.new(status_code, "Invalid JSON response: #{body[0, 200]}", body)
+      end
+    end
+  end
+end

data/lib/auto_api/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AutoApi
+  # Base exception for all auto-api.com API errors.
+  class ApiError < StandardError
+    # @return [Integer] HTTP status code returned by the API
+    attr_reader :status_code
+
+    # @return [String, nil] raw response body from the API
+    attr_reader :response_body
+
+    # @param status_code [Integer] HTTP status code
+    # @param message [String] error message
+    # @param response_body [String, nil] raw response body
+    def initialize(status_code, message, response_body = nil)
+      @status_code = status_code
+      @response_body = response_body
+      super("API error #{status_code}: #{message}")
+    end
+  end
+
+  # Exception for authentication errors (HTTP 401/403).
+  class AuthError < ApiError
+    # @param status_code [Integer] HTTP status code (401 or 403)
+    # @param message [String] error message
+    # @param response_body [String, nil] raw response body
+    def initialize(status_code, message, response_body = nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(status_code, message, response_body)
+    end
+  end
+end

data/lib/auto_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AutoApi
+  VERSION = "1.0.0"
+end

data/lib/auto_api.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "auto_api/version"
+require_relative "auto_api/errors"
+require_relative "auto_api/client"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: auto-api-client
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- AUTO-API.COM
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-11 00:00:00.000000000 Z
+dependencies: []
+description: Access car listings from encar, mobile.de, autoscout24, che168 and other
+  marketplaces via auto-api.com.
+email:
+- support@auto-api.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/auto_api.rb
+- lib/auto_api/client.rb
+- lib/auto_api/errors.rb
+- lib/auto_api/version.rb
+homepage: https://github.com/autoapicom/auto-api-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/autoapicom/auto-api-ruby
+  source_code_uri: https://github.com/autoapicom/auto-api-ruby
+  changelog_uri: https://github.com/autoapicom/auto-api-ruby/blob/main/CHANGELOG.md
+  keywords: encar api, mobile.de api, autoscout24 api, che168 api, dongchedi api,
+    guazi api, dubicars api, dubizzle api
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Ruby client for auto-api.com
+test_files: []