{"id":15918235,"url":"https://github.com/mileszim/documentcloud","last_synced_at":"2025-08-25T01:36:54.063Z","repository":{"id":49730413,"uuid":"14358583","full_name":"mileszim/documentcloud","owner":"mileszim","description":"Rubygem for interacting with the DocumentCloud API","archived":false,"fork":false,"pushed_at":"2018-08-12T19:34:11.000Z","size":38,"stargazers_count":0,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-19T03:13:23.641Z","etag":null,"topics":["api-wrapper","documentcloud","documentcloud-api","rubygems"],"latest_commit_sha":null,"homepage":null,"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/mileszim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-11-13T08:42:55.000Z","updated_at":"2018-08-31T17:51:25.000Z","dependencies_parsed_at":"2022-09-10T08:41:34.083Z","dependency_job_id":null,"html_url":"https://github.com/mileszim/documentcloud","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mileszim%2Fdocumentcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mileszim%2Fdocumentcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mileszim%2Fdocumentcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mileszim%2Fdocumentcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mileszim","download_url":"https://codeload.github.com/mileszim/documentcloud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245235793,"owners_count":20582306,"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":["api-wrapper","documentcloud","documentcloud-api","rubygems"],"created_at":"2024-10-06T18:41:13.333Z","updated_at":"2025-03-24T08:33:33.845Z","avatar_url":"https://github.com/mileszim.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DocumentCloud RubyGem #\n[![Gem Version](https://badge.fury.io/rb/documentcloud.png)](http://badge.fury.io/rb/documentcloud)\n[![Build Status](https://travis-ci.org/mileszim/documentcloud.svg?branch=master)](https://travis-ci.org/mileszim/documentcloud)\n\nRubygem for interacting with the DocumentCloud API\n\n\n## Install ##\nAdd to your Gemfile\n``` ruby\ngem 'documentcloud', '~\u003e 0.5.0'\n```\n\n## Authentication ##\n\n#### Ruby applications or Rails \u003c 5.1 ####\nUse a gem like dotenv or manually add them:\n\n``` bash\n$ DOCUMENTCLOUD_EMAIL='myemail@emailprovider.tld' \\\nDOCUMENTCLOUD_PASSWORD='my super secure password' \\\nruby main.rb\n```\n\nYou can then initialize using `ENV['DOCUMENTCLOUD_EMAIL']` (and pass) in either client or for rails, an initializer:\n\nAdd file `config/intializers/documentcloud.rb`:\n``` ruby\nDocumentCloud.configure do |config|\n  config.email = ENV['DOCUMENTCLOUD_EMAIL']\n  config.password = ENV['DOCUMENTCLOUD_PASSWORD']\nend\n```\n\n\n#### Rails \u003e= 5.1 ####\nAdd file `config/intializers/documentcloud.rb`:\n``` ruby\nDocumentCloud.configure do |config|\n  config.email = Rails.application.credentials.documentcloud[:email]\n  config.password = Rails.application.credentials.documentcloud[:password]\nend\n```\n\n##### Rails 5.1 #####\n[Add your documentcloud credentials using Rails 5.1 encrypted secrets](https://www.engineyard.com/blog/encrypted-rails-secrets-on-rails-5.1)\n\n##### Rails 5.2 #####\n[Add your documentcloud credentials using Rails 5.2 encrypted secrets](https://medium.com/cedarcode/rails-5-2-credentials-9b3324851336)\n\n\n### Search ###\nAll search results return Document objects that has methods and accessors for the information.\n\n``` ruby\nsearch = DocumentCloud.search('my query')\n\nputs search.total # returns number of results\n\nputs search.documents[0].pdf\n```\n\n\n### Upload ###\nYou can upload a document by providing a ruby File object, or a string with the url to a file.\n\n``` ruby\nlocal_doc = DocumentCloud.upload(File.new('/my/file/path.pdf','rb'), 'My Document Title')\n\nremote_doc = DocumentCloud.upload('http://somesite.com/file.pdf', 'Document Title')\n```\n\nBoth return a document object which can then be used.\n\n\n## Objects ##\nThis gem creates several objects built from the JSON response in order to provide convenience methods and accessors.\n\n### Document ###\nDocument objects wrap any document JSON. They are returned in search results, upload, and document methods.\n\n``` ruby\ndoc = DocumentCloud.document('1234-document-id')\n\n# Accessors\ndoc.id\ndoc.title\ndoc.access\ndoc.pages\ndoc.description\ndoc.source\ndoc.canonical_url\ndoc.language\ndoc.display_langauge\n\n# Methods\ndoc.pdf               # Full URL to pdf\ndoc.print_annotations\ndoc.related_article\ndoc.text              # Raw parsed text from document\ndoc.thumbnail         # Primary thumbnail of document\ndoc.entities          # Returns a hash of entities and their relevance\n\n# Images\ndoc.image(page, size) # Returns the image of a page at the specified size\n```\n\n### Search Results ###\nSearchResults objects return information about the search, and an array of Document objects\n\n``` ruby\nresults = DocumentCloud.search('my query')\n\nresults.total    # Total number of results\nresults.page     # The current results page. Used by specifying page param: DocumentCloud.search('my query', page: 2)\nresults.per_page # Number of results per page\nresults.query    # Query string\n\nresults.documents # Array of documents of results:\n\nresults.documents[0].title # First result title\n```\n\n### Projects ###\nProjects returns an array of Project objects which contain a list of Documents and\nmetadata about the project.\n\n``` ruby\nprojects = DocumentCloud.projects\n\nproject = projects.first\n\n# Accessors\nproject.id\nproject.title\nproject.description\nproject.documents # Returns an array of Document objects\n```\n\n### Entities ###\nEntities takes a document id and returns a hash of entities, which\ninclude a value and relevance for each type of entity.\n\n``` ruby\nentities = DocumentCloud.entities(2072158)\n\n# example output\n{\n  :person =\u003e [\n    { :value =\u003e \"Pita Sharples\", :relevance =\u003e 0.112 }\n  ],\n  :organization =\u003e [\n    { :value =\u003e \"Māori Party\", :relevance =\u003e 0.48 }\n  ],\n  :place =\u003e [],\n  :term =\u003e [\n    { :value =\u003e \"finance costs\", :relevance =\u003e 0.552 },\n    { :value =\u003e \"public services\", :relevance =\u003e 0.526 }\n  ],\n  :email =\u003e [],\n  :phone =\u003e [],\n  :city =\u003e [],\n  :state =\u003e [],\n  :country =\u003e [\n    { :value =\u003e \"New Zealand\", :relevance =\u003e 0.628 },\n    { :value =\u003e \"Australia\", :relevance =\u003e 0.302 },\n    { :value =\u003e \"United States\", :relevance =\u003e 0.295 },\n    { :value =\u003e \"United Kingdom\", :relevance =\u003e 0.295 },\n    { :value =\u003e \"China\", :relevance =\u003e 0.294 }\n  ]\n}\n```\n\n\n## Information ##\n\nDocumentCloud API info: http://www.documentcloud.org/help/api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmileszim%2Fdocumentcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmileszim%2Fdocumentcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmileszim%2Fdocumentcloud/lists"}