{"id":13463431,"url":"https://github.com/hakanensari/vacuum","last_synced_at":"2025-05-15T03:03:28.556Z","repository":{"id":978420,"uuid":"778943","full_name":"hakanensari/vacuum","owner":"hakanensari","description":"Amazon Product Advertising API in Ruby","archived":false,"fork":false,"pushed_at":"2024-08-18T14:06:01.000Z","size":1754,"stargazers_count":559,"open_issues_count":3,"forks_count":82,"subscribers_count":33,"default_branch":"main","last_synced_at":"2025-04-03T10:07:20.157Z","etag":null,"topics":["amazon","amazon-product-advertising","product-advertising-api","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hakanensari.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-07-16T14:25:35.000Z","updated_at":"2025-01-26T05:45:12.000Z","dependencies_parsed_at":"2024-12-18T19:03:57.054Z","dependency_job_id":"3bc900eb-d1b2-4ddb-9c18-b059ab151fc3","html_url":"https://github.com/hakanensari/vacuum","commit_stats":{"total_commits":1056,"total_committers":24,"mean_commits":44.0,"dds":"0.24715909090909094","last_synced_commit":"216e6c2f099d34c7cbcd098e91745f5286101359"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakanensari%2Fvacuum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakanensari%2Fvacuum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakanensari%2Fvacuum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hakanensari%2Fvacuum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hakanensari","download_url":"https://codeload.github.com/hakanensari/vacuum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368458,"owners_count":21092364,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","amazon-product-advertising","product-advertising-api","ruby"],"created_at":"2024-07-31T13:00:53.336Z","updated_at":"2025-05-15T03:03:28.540Z","avatar_url":"https://github.com/hakanensari.png","language":"Ruby","funding_links":[],"categories":["Web Apps, Services \u0026 Interaction","Ruby"],"sub_categories":["API Clients"],"readme":"# Vacuum\n\n[![Build](https://github.com/hakanensari/vacuum/workflows/build/badge.svg)](https://github.com/hakanensari/vacuum/actions)\n[![Maintainability](https://api.codeclimate.com/v1/badges/ffbab4aa5fedf5780332/maintainability)](https://codeclimate.com/github/hakanensari/vacuum/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/ffbab4aa5fedf5780332/test_coverage)](https://codeclimate.com/github/hakanensari/vacuum/test_coverage)\n\nVacuum is a Ruby wrapper to [Amazon Product Advertising API 5.0](https://webservices.amazon.com/paapi5/documentation/). The API provides programmatic access to query product information on the Amazon marketplaces.\n\nCart Form functionality is not covered by this gem but is a primary focus on [carriage gem](https://github.com/skatkov/carriage)\n\nYou need to [register first](https://webservices.amazon.com/paapi5/documentation/register-for-pa-api.html) to use the API.\n\n![vacuum](https://github.com/hakanensari/vacuum/blob/main/images/vacuum.jpg?raw=true)\n\n## Usage\n\n### Getting Started\n\nCreate a request with your marketplace credentials. Set the marketplace by passing its two-letter country code.\n\n```ruby\nrequest = Vacuum.new(marketplace: 'US',\n                     access_key: '\u003cACCESS_KEY\u003e',\n                     secret_key: '\u003cSECRET_KEY\u003e',\n                     partner_tag: '\u003cPARTNER_TAG\u003e')\n```\n\nYou can now access the API using the available operations.\n\n```ruby\nresponse = request.search_items(title: 'lean startup')\nputs response.to_h\n```\n\n### Operations\n\nRefer to the [API docs](https://webservices.amazon.com/paapi5/documentation/) for more detailed information.\n\n#### GetBrowseNodes\n\nGiven a BrowseNodeId, the `GetBrowseNodes` operation returns details about the specified browse node, like name, children and ancestors, depending on the resources specified in the request. The names and browse node IDs of the children and ancestor browse nodes are also returned. `GetBrowseNodes` enables you to traverse the browse node hierarchy to find a browse node.\n\n```ruby\nrequest.get_browse_nodes(\n  browse_node_ids: ['283155', '3040'],\n  resources: ['BrowseNodes.Ancestor', 'BrowseNodes.Children']\n)\n```\n\n#### GetItems\n\nGiven an Item identifier, the `GetItems` operation returns the item attributes, based on the resources specified in the request.\n\n```ruby\nrequest.get_items(\n  item_ids: ['B0199980K4', 'B000HZD168', 'B01180YUXS', 'B00BKQTA4A'],\n  resources: ['Images.Primary.Small', 'ItemInfo.Title', 'ItemInfo.Features',\n              'Offers.Summaries.HighestPrice' , 'ParentASIN']\n)\n```\n\n#### GetVariations\n\nGiven an ASIN, the `GetVariations` operation returns a set of items that are the same product, but differ according to a consistent theme, for example size and color. These items which differ according to a consistent theme are called variations. A variation is a child ASIN. The parent ASIN is an abstraction of the children items. For example, a shirt is a parent ASIN and parent ASINs cannot be sold. A child ASIN would be a blue shirt, size 16, sold by MyApparelStore. This child ASIN is one of potentially many variations. The ways in which variations differ are called dimensions.\n\n```ruby\nrequest.get_variations(\n  asin: 'B00422MCUS',\n  resources: ['ItemInfo.Title', 'VariationSummary.Price.HighestPrice',\n              'VariationSummary.Price.LowestPrice',\n              'VariationSummary.VariationDimension']\n)\n```\n\n#### SearchItems\n\nThe `SearchItems` operation searches for items on Amazon based on a search query. The API returns up to ten items per search request.\n\n```ruby\nrequest.search_items(keywords: 'harry potter')\n```\n\n### Response\n\nConsume a response by parsing it into a Ruby hash.\n\n```ruby\nresponse.to_h\n```\n\nYou can also `#dig` into this hash.\n\n```ruby\nresponse.dig('ItemsResult', 'Items')\n```\n\n### Logging\n\nWrite requests and reponses to a logger using the logging feature of the [HTTP gem](https://github.com/httprb/http) under the hood:\n\n```ruby\nrequire 'logger'\n\nlogger = Logger.new(STDOUT)\nrequest.use(logging: {logger: logger})\n```\n\n### Bring your parser\n\nYou can extend Vacuum with a custom parser. Just swap the original with a class or module that responds to `.parse`.\n\n```ruby\nresponse.parser = MyParser\nresponse.parse\n```\n\nIf no custom parser is set, `Vacuum::Response#parse` delegates to `#to_h`.\n\n### VCR\n\nIf you are using [VCR](https://github.com/vcr/vcr) to test an app that accesses the API, you can use the custom VCR matcher of Vacuum to stub requests.\n\n```ruby\nrequire 'vacuum/matcher'\n\n# in your test\nVCR.insert_cassette('cassette_name',\n                    match_requests_on: [Vacuum::Matcher])\n```\n\nIn RSpec, use the `:paapi` metadata.\n\n```ruby\nrequire 'vacuum/matcher'\n\n# in your test\nit 'queries Amazon', :paapi do\nend\n```\n\n## Development\n\nClone the repo and install dependencies.\n\n```sh\nbundle install\n```\n\nTests and Rubocop should now pass as-is.\n\n```sh\nbundle exec rake\n```\n\nBy default, the tests stub requests. Use the `RECORD` env var to record new interactions.\n\n```sh\nRECORD=true bundle exec rake test\n```\n\nYou can set the `LIVE` env var to run all tests against live data.\n\n```sh\nLIVE=true bundle exec rake test\n```\n\nIn either case, add actual API credentials to a [`locales.yml`](https://github.com/hakanensari/vacuum/blob/master/test/locales.yml.example) file under `test`.\n\n## Getting Help\n\n- Ask specific questions about the API on the [Amazon forum](https://forums.aws.amazon.com/forum.jspa?forumID=9).\n- Report bugs in [GitHub issues](https://github.com/hakanensari/vacuum/issues).\n- Discuss potential features in [GitHub Discussions](https://github.com/hakanensari/vacuum/discussions).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakanensari%2Fvacuum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhakanensari%2Fvacuum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhakanensari%2Fvacuum/lists"}