{"id":13858611,"url":"https://github.com/strong-code/pirata","last_synced_at":"2025-07-14T00:32:01.797Z","repository":{"id":16633172,"uuid":"19388331","full_name":"strong-code/pirata","owner":"strong-code","description":"Ruby gem that provides an API for ThePirateBay torrent tracker. Viva il pirata!","archived":false,"fork":false,"pushed_at":"2023-02-19T17:34:18.000Z","size":115,"stargazers_count":55,"open_issues_count":4,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-30T00:27:21.595Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/pirata","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strong-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2014-05-02T20:54:12.000Z","updated_at":"2021-03-08T11:38:18.000Z","dependencies_parsed_at":"2023-07-14T19:08:14.773Z","dependency_job_id":"a1e79db9-b524-444a-b4ac-315dd4d5ed91","html_url":"https://github.com/strong-code/pirata","commit_stats":null,"previous_names":["clindsay107/pirata"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strong-code%2Fpirata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strong-code%2Fpirata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strong-code%2Fpirata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strong-code%2Fpirata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strong-code","download_url":"https://codeload.github.com/strong-code/pirata/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225930042,"owners_count":17547098,"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":[],"created_at":"2024-08-05T03:02:14.958Z","updated_at":"2024-11-22T16:31:26.833Z","avatar_url":"https://github.com/strong-code.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# Pirata\n[![Gem Version](https://badge.fury.io/rb/pirata.svg)](http://badge.fury.io/rb/pirata) [![Pirata API Documentation](https://www.omniref.com/ruby/gems/pirata.png)](https://www.omniref.com/ruby/gems/pirata)\n\n**Note: I'm available for consulting and contract software development work. If you're\nlooking to build a website, API, automation or scraping services then get in touch: [colin@strongco.de](mailto:colin@strongco.de)**\n\nPirata is a Ruby gem that exposes a useful and easy to use API for the popular\ntorrent tracker [ThePirateBay](http://thepiratebay.se). It aims to give developers\na simple way to incorporate the torrent and website data into their applications.\n\n# Usage\n## Quick Start Guide\n**Note** As the `nokogiri` gem is a runtime dependency of this one, it is highly\nrecommended you install that before hand like so:\n\n    $ env NOKOGIRI_USE_SYSTEM_LIBRARIES=true gem install nokogiri\n\nThe reason for this is that `nokogiri` attempts to compile libxml2 and libxslt\nat installation. Substituting already-installed system libraries will cut down\ndrastically on the installation time. This is not required, but hopefully will be helpful.\n\n### Quick Start\n\nFirst, download pirata with `gem install pirata`\n\nNext, require it (either in IRB or your .rb file) `require 'pirata'`\n\nNow you are free to play with Pirata! Here are some examples\n```ruby\n# A basic search across all categories\nsearch = Pirata::Search.new(\"zelda reorchestrated\") # =\u003e Return a Pirata::Search object\nsearch.results # =\u003e An array of Torrent objects resulting from the search\nsearch.results.first # =\u003e A Pirata::Torrent object. See the below table for available methods\n\n# Get an array of the top 100 Torrents\ntop_hundred = Pirata::Search.top\n\n# Now within a specified category\ntop_hundred_videos = Pirata::Search.top(Pirata::Category::VIDEO)\n\n# Get an array of the 30 most recent uploaded Torrents\nmost_recent = Pirata::Search.recent\n\n# You can also find detailed information on a Torrent if you know its ID\nPirata::Torrent.find_by_id(5241636)\n```\n\n## Advanced Searching\n```ruby\n# Order results by Seeders\ntorrents = Pirata::Search.new(\"open source\", Pirata::Sort::SEEDERS).results\n\n# Order results by Date, search only in Video and Applications categories\ntorrents = Pirata::Search.new(\"open source\", Pirata::Sort::DATE, [Pirata::Category::VIDEO, Pirata::Category::APPLICATIONS]).results\n\n# Check if a search is multipage\nquery = Pirata::Search.new(\"open source\").multipage? # =\u003e true\n\n# Find the last page number\nquery.pages # =\u003e 3\n\n# Perform a search on a page beyond the first\nquery.search_page(2)\n```\n\n## Torrent Objects\n`torrent = Pirata::Search.new(\"zelda\").results.first`\n\n| Method     | Result               | Example value                                   | Return Type |\n|------------|----------------------|-------------------------------------------------|-------------|\n| #title     | Torrent title        | \"Cylum's 'The Legend of Zelda' ROM Collection\"  | String      |\n| #category  | Torrent category     | \"Games\"                                         | String      |\n| #url       | Full URL             | \"http://thepiratebay.si/torrent/10080116/Cyl...\"| String      |\n| #id        | Numeric ID           | 10080116                                        | Fixnum      |\n| #magnet    | Torrent magnet link  | \"magnet:?xt=urn:btih:30f784d135af21152052a...\"  | String      |\n| #seeders   | Number of seeders    | 4                                               | Fixnum      |\n| #leechers  | Number of leechers   | 0                                               | Fixnum      |\n| #uploader  | User who uploaded torrent | #\u003cPirata::User:0x0000000260f200\u003e           | Pirata::User|\n\nNote: The following methods require an extra request to be made, but the first request (regardless of\nwhich method you call) will fetch and populate data for all other calls for the same Torrent object.\n\n| Method     | Result               | Example value                                   | Return Type |\n|------------|----------------------|-------------------------------------------------|-------------|\n| #files     | Number of files      | 51                                              | Fixnum      |\n| #size      | Total torrent size   | \"224.95 MiB (235876575 Bytes)\"                  | String      |\n| #comments  | Number of comments   | 0                                               | Fixnum      |\n| #hash      | Alphanumeric hash    | \"30F784D135AF21152052A45AE718A7FCAB597A79\"      | String      |\n| #date      | Date of upload       | 2002-01-01 00:00:00 -0500                       | Time        |\n\n## User Objects\n\n| Method     | Result               | Example value                                   | Return Type |\n|------------|----------------------|-------------------------------------------------|-------------|\n| #username  | Username string      | \"LXZX\"                                          | String      |\n| #profile_url | URL for the user profile | \"http://thepiratebay.si/user/LXZX\"        | String      |\n\n# Categories\nSearches by default will query across all categories. However you can choose to narrow your search down\nby passing an array of categories. These are all namespaced under Pirata::Category. **Please note:** These\nare only the main/topmost categories for searching - there are subcategories for each category listed below\n(but the list is too large to be pasted here). Please reference `lib/pirata/category.rb` for an entire\nlist of possible search categories.\n\n```ruby\n    AUDIO         = \"100\"\n    VIDEO         = \"200\"\n    APPLICATIONS  = \"300\"\n    GAMES         = \"400\"\n    PORN          = \"500\"\n    OTHER         = \"600\"\n```\n\n# Sorting\nBy default, results are sorted by ThePirateBay's relevance algorithm. While you could manually sort Torrent\nobjects by writing your own comparator, you can also pass a `Pirata::Sort` constant to your search and\nhave the results returned to you in whichever sorting fashion you choose.\n```ruby\n    RELEVANCE   = \"99\"\n    TYPE        = \"13\"\n    NAME        = \"1\"\n    DATE        = \"3\"\n    SIZE        = \"5\"\n    UPLOADER    = \"11\"\n    SEEDERS     = \"7\"\n    LEECHERS    = \"9\"\n```\n\n# Config\nThe root `Pirata` namespace has an instance method `Pirata.configure` which accepts an options\nhash. There are 2 values accepted - `:base_url` and `:redirect`. The former refers to the\nmirror site you wish to use. ThePirataBay is notorious for going down and coming back up under\na new domain. Because of this, you may have to change the domain you are querying against if\nyou find you are running into trouble. Luckily, there are a lot of great people who host TPB\nmirror/proxy sites for free! If you find you are getting timeout errors, you can set the base\nurl to a working proxy.\n\nA list of mirror sites can be found at [TheProxyBay](http://proxybay.info/)\n\nThere is also a rule for HTTP redirection. When specifying a protocol in the `:base_url` value, you may choose to\nuse `http` or `https`. The `open_uri_redirections` patch allows HTTP \u003c-\u003e HTTPS redirections, but requires a rule\nto be specified. You can use `:safe` or `:all`. The former only does HTTP -\u003e HTTPS redirection, while the latter\nwill do both. By default, it is set to `:all`.\n\nThe default configuration looks like this:\n```ruby\n@config = {\n  :base_url =\u003e 'https://pirateproxy.tv/',\n  :redirect =\u003e :all\n}\n```\n\nand can be overridden with `Pirata.configure({:base_url =\u003e 'http://someproxy.com', :redirect =\u003e :safe})`\n\nThe configuration can be accessed with `Pirata.config`, which will return a hash. Note that all keys are symbols.\n\n# Testing\nThere is a basic test suite you can run that will test against basic use cases and functionaliy. The big problem\nwith testing this gem is that 1) the data is always changing for search results as things get uploaded or removed,\ncomments get added, leechers/seeders get added or dropped off, etc, and 2) ThePirateBay could go offline. You can\nrun tests by simply running `rake` in the parent Pirata directory. If you find you are getting errors (but not\nfailures), ensure that the domain you are using in `Pirata.config[:base_url]` is actually up. Otherwise, please\nfeel free to submit a Github issue and I'll get to it asap. Or fork it and help out!\n\n# License\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrong-code%2Fpirata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrong-code%2Fpirata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrong-code%2Fpirata/lists"}