{"id":13595983,"url":"https://github.com/speric/kindle-highlights","last_synced_at":"2025-04-09T13:33:55.583Z","repository":{"id":2081141,"uuid":"3020573","full_name":"speric/kindle-highlights","owner":"speric","description":"Get your Kindle highlights.","archived":false,"fork":false,"pushed_at":"2020-04-04T01:12:01.000Z","size":50,"stargazers_count":568,"open_issues_count":10,"forks_count":51,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-04-26T22:03:21.647Z","etag":null,"topics":["books","kindle","reading"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/kindle-highlights","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/speric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-12-20T15:54:17.000Z","updated_at":"2024-04-02T18:26:02.000Z","dependencies_parsed_at":"2022-08-20T23:10:46.110Z","dependency_job_id":null,"html_url":"https://github.com/speric/kindle-highlights","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speric%2Fkindle-highlights","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speric%2Fkindle-highlights/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speric%2Fkindle-highlights/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/speric%2Fkindle-highlights/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/speric","download_url":"https://codeload.github.com/speric/kindle-highlights/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248049802,"owners_count":21039276,"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":["books","kindle","reading"],"created_at":"2024-08-01T16:02:03.486Z","updated_at":"2025-04-09T13:33:55.300Z","avatar_url":"https://github.com/speric.png","language":"Ruby","funding_links":[],"categories":["Ruby","Ebook Tools"],"sub_categories":["Manager"],"readme":"## kindle-highlights\n\n[![build status](https://secure.travis-ci.org/speric/kindle-highlights.png)](http://travis-ci.org/speric/kindle-highlights)\n\nA Ruby gem for collecting your Kindle highlights.\n\n### Requirements\n\n* Ruby `2.1.0` or greater\n* An Amazon Kindle account\n\n### Install\n```\ngem install kindle-highlights\n```\n\n### Use\n\nFirst, `require` the gem and initialize a new client by passing in the email address \u0026 password you use\nto sign into your Amazon Kindle account:\n\n```ruby\nrequire 'kindle_highlights'\n\nkindle = KindleHighlights::Client.new(\n  email_address: \"email.address@gmail.com\",\n  password: \"password\"\n)\n```\n\n### Fetching a list of your Kindle books\n\nUse the `books` method to get a listing of all your Kindle books. This method\nreturns a collection of `KindleHighlights::Book` objects:\n\n```ruby\nkindle.books\n#=\u003e\n[\n  \u003cKindleHighlights::Book:\n      @asin=\"B000XUAETY\",\n      @author=\"James R. Mcdonough\",\n      @title=\"Platoon Leader: A Memoir of Command in Combat\"\n  \u003e,\n  \u003cKindleHighlights::Book:\n    @asin=\"B003XDUCEU\",\n    @author=\"Michael Lopp\",\n    @title=\"Being Geek: The Software Developer's Career Handbook\"\n  \u003e,\n  \u003cKindleHighlights::Book:\n    @asin=\"B00JJ1RIO2\",\n    @author=\"James K. A. Smith\",\n    @title=\"How (Not) to Be Secular: Reading Charles Taylor\"\n  \u003e\n]\n```\n\nEach `Book` object has it's `asin`, `author`, and `title` as attributes:\n\n```ruby\nbook = kindle.books.first\nbook.asin\n#=\u003e \"B000XUAETY\"\nbook.author\n#=\u003e \"James R. Mcdonough\"\nbook.title\n#=\u003e \"Platoon Leader: A Memoir of Command in Combat\"\n```\n\n### Fetching all highlights for a single book\n\nTo get only the highlights for a specific book, use the `highlights_for` method, passing\nin the book's Amazon ASIN as the only method parameter. This method returns a collection of\n`KindleHighlights::Highlight` objects:\n\n```ruby\nkindle.highlights_for(\"B005CQ2ZE6\")\n#=\u003e\n[\n  \u003cKindleHighlights::Highlight:0x007fc4e7e03ea0\n    @asin=\"B005CQ2ZE6\",\n    @text=\"One of the most dangerous things you can believe in this world is that technology is neutral.\",\n    @location=\"197\"\n  \u003e\n]\n```\n\nEach `Highlight` object has the book's `asin`, the `text` of the highlight, and it's `location` as attributes:\n\n```ruby\nhighlight = kindle.highlights_for(\"B005CQ2ZE6\").first\n\nhighlight.asin\n#=\u003e \"B005CQ2ZE6\"\nhighlight.text\n#=\u003e \"One of the most dangerous things you can believe in this world is that technology is neutral.\"\nhighlight.location\n#=\u003e \"197\"\n```\n\nAdditionally, each book has it's own `highlights_from_amazon` method:\n\n```\nbook = kindle.books.first\nbook.highlights_from_amazon\n```\n\n### Advanced Usage\n\nThis gem uses [mechanize](https://github.com/sparklemotion/mechanize) to interact with Amazon's Kindle pages. You can override any of the default mechanize settings (see `lib/kindle_highlights/client.rb`) by passing your settings to the initializer:\n\n```ruby\nkindle = KindleHighlights::Client.new(\n  email_address: \"me@example.com\",\n  password: \"amazon_password\",\n  mechanize_options: { user_agent_alias: 'Mac Safari' }\n)\n```\n\nOr you can use `read.amazon.com` equivalents provided on other TLDs like:\n\n```ruby\nkindle = KindleHighlights::Client.new(\n  email_address: \"me@example.com\",\n  password: \"amazon_password\",\\\n  root_url: 'https://read.amazon.co.jp'\n)\n```\n\n### A Note About CAPTCHAs\n\nAmazon will sometimes issue a CAPTCHA challenge when logging in to your\nKindle account. If this happens when the gem attempts to log in to your\nKindle account to retrieve your book list or highlights, you'll get a `KindleHighlights::Client::CaptchaError`, like the following:\n\n```ruby\n\u003e kindle.books\nKindleHighlights::Client::CaptchaError: Received a CAPTCHA while attempting to sign in to your Amazon account. You will need to resolve this manually at https://www.amazon.com/ap/signin?openid.pape.max_auth_age=0\u0026openid...\n```\n\nThere's no way to programmatically resolve this situation. The best\nsolution I've found is to open a browser, visit the URL that the gem returns, log in to\nyour Kindle account, and click around a bit. Then log out of your Kindle\naccount and re-attempt to fetch your highlights via this gem. Additionally, you could try\ninstantiating a new instance of the client and changing the User-Agent\nvia `mechanize_options` like:\n\n```ruby\nkindle = KindleHighlights::Client.new(\n  email_address: \"me@example.com\",\n  password: \"amazon_password\",\n  mechanize_options: { user_agent_alias: 'iPhone' }\n)\n```\n\n### In The Wild\n* [tobi/highlights](https://github.com/tobi/highlights) - Download your Kindle highlights and email random ones to your inbox\n\n### Contributing to kindle-highlights (PRs welcome)\n\n* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet\n* Check out the [issue tracker](http://github.com/speric/kindle-highlights/issues) to make sure someone already hasn't requested it and/or contributed it\n* Fork the project\n* Start a feature/bugfix branch\n* Commit and push until you are happy with your contribution\n* Make sure to add tests for the feature/bugfix. This is important so I don't break it in a future version unintentionally.\n* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate it to its own commit so I can cherry-pick around it.\n\n### Copyright\n\nCopyright (c) 2011-2018 Eric Farkas. See MIT-LICENSE for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsperic%2Fkindle-highlights","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsperic%2Fkindle-highlights","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsperic%2Fkindle-highlights/lists"}