{"id":22289535,"url":"https://github.com/huwd/wikidata_adaptor","last_synced_at":"2026-07-08T19:31:50.377Z","repository":{"id":217107321,"uuid":"647975067","full_name":"huwd/wikidata_adaptor","owner":"huwd","description":"An API wrapper to interact with Wikidata and Wikibase APIs","archived":false,"fork":false,"pushed_at":"2026-06-13T22:03:08.000Z","size":320,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T23:22:53.922Z","etag":null,"topics":["api-wrapper","ruby","wikidata"],"latest_commit_sha":null,"homepage":"https://huwd.github.io/wikidata_adaptor/","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/huwd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-31T23:56:24.000Z","updated_at":"2026-06-13T21:59:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"8861f7f5-f927-4dcc-807f-8a7f506cd221","html_url":"https://github.com/huwd/wikidata_adaptor","commit_stats":null,"previous_names":["huwd/wikidata_adaptor"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/huwd/wikidata_adaptor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huwd%2Fwikidata_adaptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huwd%2Fwikidata_adaptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huwd%2Fwikidata_adaptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huwd%2Fwikidata_adaptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huwd","download_url":"https://codeload.github.com/huwd/wikidata_adaptor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huwd%2Fwikidata_adaptor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35276647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","ruby","wikidata"],"created_at":"2024-12-03T17:09:22.727Z","updated_at":"2026-07-08T19:31:50.371Z","avatar_url":"https://github.com/huwd.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WikidataAdaptor\n\n[![Quality Checks](https://github.com/huwd/wikidata_adaptor/actions/workflows/quality-checks.yml/badge.svg)](https://github.com/huwd/wikidata_adaptor/actions/workflows/quality-checks.yml)\n[![Documentation](https://github.com/huwd/wikidata_adaptor/actions/workflows/docs.yml/badge.svg)](https://github.com/huwd/wikidata_adaptor/actions/workflows/docs.yml)\n\nA Ruby gem providing a clean, well-documented interface to the [Wikibase REST API](https://doc.wikimedia.org/Wikibase/master/js/rest-api/). Interact with Wikidata and other Wikibase instances to read and write structured data.\n\n## Features\n\n- **100% API coverage** - All 65 endpoints from Wikibase REST API v1.4\n- **Fully documented** - 100% YARD documentation coverage\n- **Well-tested** - Comprehensive unit and integration test suites\n- **Structured JSON responses** - Consistent response shapes from the API\n- **Test helpers included** - WebMock stubs for easy testing in your applications\n\nSupported operations:\n- **Items \u0026 Properties** - Create, read, update (GET, POST, PATCH)\n- **Labels** - Multi-language labels with fallback support (GET, PUT, PATCH, DELETE)\n- **Descriptions** - Multi-language descriptions (GET, PUT, PATCH, DELETE)\n- **Aliases** - Alternative names in multiple languages (GET, POST, PATCH)\n- **Statements** - Claims and references (GET, POST, PUT, PATCH, DELETE)\n- **Sitelinks** - Links to related wiki pages (GET, PUT, PATCH, DELETE)\n- **Search** - Full-text search and autocomplete suggestions\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"wikidata_adaptor\"\n```\n\nThen execute:\n\n```bash\nbundle install\n```\n\nOr install directly:\n\n```bash\ngem install wikidata_adaptor\n```\n\n## Quick Start\n\n```ruby\nrequire \"wikidata_adaptor\"\n\n# Create a client\nclient = WikidataAdaptor.rest_api\n\n# Get an item (Douglas Adams - Q42)\nitem = client.get_item(\"Q42\")\nputs item[\"labels\"][\"en\"]  # =\u003e \"Douglas Adams\"\n\n# Get labels in a specific language\nlabels = client.get_item_labels(\"Q42\")\nputs labels[\"en\"]  # =\u003e \"Douglas Adams\"\nputs labels[\"fr\"]  # =\u003e \"Douglas Adams\"\n\n# Search for items\nresults = client.search_items(\"Douglas Adams\")\nresults.each do |result|\n  puts \"#{result['id']}: #{result['label']}\"\nend\n```\n\n## Documentation\n\n- **[API Documentation](https://huwd.github.io/wikidata_adaptor/)** - Full YARD documentation\n- **[Wikibase REST API Reference](https://doc.wikimedia.org/Wikibase/master/js/rest-api/)** - Official API docs\n- **[CHANGELOG](CHANGELOG.md)** - Version history and changes\n\n## Usage\n\n### Reading Data\n\n```ruby\n# Get an item with all its data\nitem = client.get_item(\"Q42\")\n\n# Get specific language label\nlabel = client.get_item_label(\"Q42\", \"en\")\n\n# Get label with language fallback\nlabel = client.get_item_label_with_language_fallback(\"Q42\", \"en-gb\")\n\n# Get descriptions\ndesc = client.get_item_description(\"Q42\", \"en\")\n\n# Get aliases\naliases = client.get_item_aliases(\"Q42\")\n\n# Get statements (claims)\nstatements = client.get_item_statements(\"Q42\")\n\n# Filter statements by property\nstatements = client.get_item_statements(\"Q42\", property: \"P31\")  # instance of\n```\n\n### Search\n\n```ruby\n# Full-text search\nresults = client.search_items(\"Albert Einstein\")\n\n# Autocomplete suggestions\nsuggestions = client.suggest_items(\"Einst\")\n\n# Search properties\nproperties = client.search_properties(\"instance of\")\n```\n\n### Writing Data (requires authentication)\n\n```ruby\n# Configure an authenticated REST API client with a bearer token\nrest_api = WikidataAdaptor::RestApi.new(\n  \"https://www.wikidata.org/w/rest.php/wikibase\",\n  bearer_token: \"your_oauth_token\"\n)\n\n# Build a WikidataAdaptor client using the authenticated REST API instance\nclient = WikidataAdaptor::Client.new(rest_api: rest_api)\n# Create a new item\nnew_item = client.post_item({\n  item: {\n    labels: { en: \"My New Item\" },\n    descriptions: { en: \"A test item\" }\n  },\n  comment: \"Creating test item\"\n})\n\n# Update a label\nclient.put_item_label(\"Q42\", \"en\", {\n  label: \"Douglas Noël Adams\",\n  comment: \"Adding middle name\"\n})\n\n# Add a statement\nclient.post_item_statement(\"Q42\", {\n  statement: {\n    property: { id: \"P31\" },\n    value: { content: \"Q5\", type: \"item\" }\n  },\n  comment: \"Adding instance of human\"\n})\n\n# Delete a label\nclient.delete_item_label(\"Q42\", \"en\", {\n  comment: \"Removing English label\"\n})\n```\n\n### Using Different Wikibase Instances\n\nBy default, the gem connects to Wikidata. To use a different Wikibase instance:\n\n```ruby\nENV[\"WIKIBASE_REST_ENDPOINT\"] = \"https://your-wikibase.org/w/rest.php/wikibase\"\nclient = WikidataAdaptor.rest_api\n```\n\n### Test Helpers\n\nThe gem includes WebMock test helpers for easy testing:\n\n```ruby\nrequire \"wikidata_adaptor/test_helpers/rest_api\"\n\nRSpec.describe MyClass do\n  include WikidataAdaptor::TestHelpers::RestApi\n\n  it \"fetches an item\" do\n    stub_get_item(\"Q42\")  # Stubs the API call\n\n    result = MyClass.fetch_item(\"Q42\")\n    expect(result[\"labels\"][\"en\"]).to eq(\"Douglas Adams\")\n  end\nend\n```\n\nSee the [test helpers documentation](https://huwd.github.io/wikidata_adaptor/WikidataAdaptor/TestHelpers/RestApi.html) for all available stubs.\n\n## Development\n\nAfter checking out the repository:\n\n```bash\n# Install dependencies\nbundle install\n\n# Run tests\nbundle exec rake           # Run all tests + RuboCop\nbundle exec rspec          # Run unit tests only\nbundle exec rubocop        # Run linter only\n\n# Generate documentation\nbundle exec rake yard\n\n# Run integration tests (requires Docker)\n./script/integration-up    # Start Wikibase instance\n./script/integration-test  # Run integration tests\n./script/integration-down  # Stop Wikibase instance\n```\n\n### Project Structure\n\n```\nlib/\n├── wikidata_adaptor/\n│   ├── rest_api.rb              # Main client class\n│   ├── rest_api/                # API endpoint modules\n│   │   ├── items.rb\n│   │   ├── labels.rb\n│   │   ├── statements.rb\n│   │   └── ...\n│   └── test_helpers/            # WebMock test stubs\n│       └── rest_api/\n│           ├── items.rb\n│           ├── labels.rb\n│           └── ...\nspec/\n├── wikidata_adaptor/rest_api/  # Unit tests\n└── integration/                 # Integration tests\n```\n\n## Requirements\n\n- Ruby \u003e= 3.2.0\n- Bundler\n\n## Contributing\n\nBug reports and pull requests are welcome on [GitHub](https://github.com/huwd/wikidata_adaptor).\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Make your changes with tests\n4. Ensure all tests pass (`bundle exec rake`)\n5. Commit following [commit conventions](CLAUDE.md#commit-standards)\n6. Push to the branch (`git push origin my-new-feature`)\n7. Create a Pull Request\n\nPlease read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\nSee [CLAUDE.md](CLAUDE.md) for detailed development guidelines including:\n- Commit standards (Conventional Commits)\n- Git workflow (branch/PR process)\n- TDD workflow\n- Testing conventions\n\n## License\n\nThis gem is available as open source under the terms of the [MIT License](LICENSE.txt).\n\n## Code of Conduct\n\nEveryone interacting in the WikidataAdaptor project is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Links\n\n- [Documentation](https://huwd.github.io/wikidata_adaptor/)\n- [Source Code](https://github.com/huwd/wikidata_adaptor)\n- [Issue Tracker](https://github.com/huwd/wikidata_adaptor/issues)\n- [Changelog](CHANGELOG.md)\n- [Wikibase REST API](https://doc.wikimedia.org/Wikibase/master/js/rest-api/)\n- [Wikidata](https://www.wikidata.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuwd%2Fwikidata_adaptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuwd%2Fwikidata_adaptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuwd%2Fwikidata_adaptor/lists"}