{"id":30196217,"url":"https://github.com/tarrball/guardianclient.net","last_synced_at":"2026-04-11T20:46:59.061Z","repository":{"id":309271015,"uuid":"1035663695","full_name":"tarrball/GuardianClient.NET","owner":"tarrball","description":"Unofficial .NET client for The Guardian Content API. Provides strongly-typed models, search helpers, and deep pagination support for developers integrating Guardian articles and metadata into .NET applications.","archived":false,"fork":false,"pushed_at":"2025-08-10T23:34:02.000Z","size":3733,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T23:54:27.055Z","etag":null,"topics":["api","articles","client","content-api","dotnet","guardian","news","search","unofficial"],"latest_commit_sha":null,"homepage":"","language":"C#","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/tarrball.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-10T21:55:34.000Z","updated_at":"2025-08-10T23:35:50.000Z","dependencies_parsed_at":"2025-08-10T23:54:29.220Z","dependency_job_id":"17ffc6b3-d0da-4eb4-b766-fefb9b7907df","html_url":"https://github.com/tarrball/GuardianClient.NET","commit_stats":null,"previous_names":["tarrball/guardianclient.net"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tarrball/GuardianClient.NET","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarrball%2FGuardianClient.NET","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarrball%2FGuardianClient.NET/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarrball%2FGuardianClient.NET/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarrball%2FGuardianClient.NET/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarrball","download_url":"https://codeload.github.com/tarrball/GuardianClient.NET/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarrball%2FGuardianClient.NET/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270183606,"owners_count":24541341,"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","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"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","articles","client","content-api","dotnet","guardian","news","search","unofficial"],"created_at":"2025-08-13T05:17:05.743Z","updated_at":"2026-04-11T20:46:59.012Z","avatar_url":"https://github.com/tarrball.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GuardianClient.NET\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/guardian.png\" width=\"150\" alt=\"Guardian knight logo\"/\u003e\n\u003c/p\u003e\n\nA modern, comprehensive .NET client library for The Guardian's Content API. Provides strongly-typed models, flexible search options, and simple methods for searching Guardian articles with full API feature support.\n\n[![NuGet Version](https://img.shields.io/nuget/v/GuardianClient.NET?logo=nuget)](https://www.nuget.org/packages/GuardianClient.NET)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/tarrball/GuardianClient.NET/deploy-nuget.yml?branch=main)](https://github.com/tarrball/GuardianClient.NET/actions)\n\n## ✨ Features\n\n- 🔍 **Complete Content Search** - Full Guardian Content API search with all parameters\n- 🏷️ **Strongly Typed** - Type-safe enums for fields, tags, elements, and references  \n- 🎯 **Comprehensive Filtering** - Search by section, tags, date ranges, production office, and more\n- 📑 **Rich Content Options** - Include fields, tags, media elements, blocks, and references\n- 🔧 **Interface-Based Design** - Easy mocking and dependency injection with `IGuardianApiClient`\n- 📦 **HttpClientFactory Ready** - Proper HttpClient lifecycle management\n- ⚡ **Modern Async** - Full async/await patterns with cancellation support\n- 🎨 **Clean API** - Organized option classes for maintainable code\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\ndotnet add package GuardianClient.NET\n```\n\n### Setup with Dependency Injection (Recommended)\n\n```csharp\n// Program.cs or Startup.cs\nbuilder.Services.AddGuardianApiClient(\"your-api-key\");\n```\n\n### Basic Usage\n\n```csharp\npublic class NewsService\n{\n    private readonly IGuardianApiClient _client;\n\n    public NewsService(IGuardianApiClient client)\n    {\n        _client = client;\n    }\n\n    public async Task\u003cContentSearchResponse?\u003e GetLatestTechNews()\n    {\n        return await _client.SearchAsync(new GuardianApiContentSearchOptions\n        {\n            Query = \"artificial intelligence\",\n            FilterOptions = new GuardianApiContentFilterOptions\n            {\n                Section = \"technology\"\n            },\n            PageOptions = new GuardianApiContentPageOptions \n            { \n                PageSize = 10 \n            }\n        });\n    }\n}\n```\n\n## 🔧 Advanced Usage\n\n### Comprehensive Search with All Options\n\n```csharp\nvar results = await client.SearchAsync(new GuardianApiContentSearchOptions\n{\n    // Search terms with boolean operators\n    Query = \"climate change AND (policy OR legislation)\",\n    QueryFields = [\"body\", \"headline\"],\n    \n    // Filtering options\n    FilterOptions = new GuardianApiContentFilterOptions\n    {\n        Section = \"environment\",\n        Tag = \"climate-change\",\n        Language = \"en\"\n    },\n    \n    // Date filtering  \n    DateOptions = new GuardianApiContentDateOptions\n    {\n        FromDate = new DateOnly(2023, 1, 1),\n        UseDate = \"published\"\n    },\n    \n    // Pagination\n    PageOptions = new GuardianApiContentPageOptions\n    {\n        Page = 1,\n        PageSize = 20\n    },\n    \n    // Ordering\n    OrderOptions = new GuardianApiContentOrderOptions\n    {\n        OrderBy = GuardianApiContentOrderBy.Relevance,\n        OrderDate = GuardianApiContentOrderDate.Published\n    },\n    \n    // Additional content\n    AdditionalInformationOptions = new GuardianApiContentAdditionalInformationOptions\n    {\n        ShowFields = [\n            GuardianApiContentShowFieldsOption.Headline,\n            GuardianApiContentShowFieldsOption.Body,\n            GuardianApiContentShowFieldsOption.Thumbnail\n        ],\n        ShowTags = [\n            GuardianApiContentShowTagsOption.Keyword,\n            GuardianApiContentShowTagsOption.Tone\n        ],\n        ShowElements = [GuardianApiContentShowElementsOption.Image]\n    }\n});\n```\n\n### Getting Individual Articles\n\n```csharp\n// Get a specific article by ID\nvar article = await client.GetItemAsync(\"world/2023/oct/15/climate-summit-agreement\",\n    new GuardianApiContentAdditionalInformationOptions\n    {\n        ShowFields = [\n            GuardianApiContentShowFieldsOption.Body,\n            GuardianApiContentShowFieldsOption.Byline\n        ],\n        ShowTags = [GuardianApiContentShowTagsOption.All]\n    });\n\n// Access the rich content\nConsole.WriteLine(article.Content.WebTitle);\nConsole.WriteLine(article.Content.Fields.Body); // Full HTML content\nConsole.WriteLine($\"Author: {article.Content.Fields.Byline}\");\n```\n\n### Manual Setup (without DI)\n\n```csharp\nusing var client = new GuardianApiClient(\"your-api-key\");\nvar results = await client.SearchAsync(new GuardianApiContentSearchOptions \n{\n    Query = \"sports\",\n    PageOptions = new GuardianApiContentPageOptions { PageSize = 5 }\n});\n\nforeach (var article in results.Results)\n{\n    Console.WriteLine($\"{article.WebTitle} - {article.WebPublicationDate}\");\n}\n```\n\n## 🔑 Getting an API Key\n\n1. Visit [The Guardian Open Platform](https://open-platform.theguardian.com/access/)\n2. Sign up for a free developer account  \n3. Generate your API key\n4. Store it securely (use User Secrets for development)\n\n## 🏗️ Available Options\n\n### Filter Options\n- **Section**: Filter by Guardian sections (e.g., \"politics\", \"sport\", \"culture\")\n- **Tags**: Filter by content tags with boolean operators\n- **Date Range**: Filter by publication date with flexible date types\n- **Language**: Filter by content language (ISO codes)\n- **Production Office**: Filter by Guardian production offices\n- **Star Rating**: Filter by review ratings (1-5)\n\n### Additional Content Options\n- **ShowFields**: Include extra fields like body content, thumbnails, bylines\n- **ShowTags**: Include metadata tags (keywords, contributors, tone)\n- **ShowElements**: Include media elements (images, videos, audio)\n- **ShowReferences**: Include reference data (ISBNs, IMDB IDs, etc.)\n- **ShowBlocks**: Include content blocks (useful for live blogs)\n\n### Ordering Options\n- **OrderBy**: Sort by newest, oldest, or relevance\n- **OrderDate**: Choose which date to use for sorting\n\n## 📊 Current Status\n\n**✅ Fully Implemented:**\n- Complete Content API search with all parameters\n- Individual article retrieval\n- Strongly-typed models and enums for all options\n- Advanced filtering, pagination, and sorting\n- Rich content enhancement options\n- Interface-based design for easy testing\n- Comprehensive documentation and examples\n\n**🎯 Feature Complete:** This library now supports the full Guardian Content API specification.\n\n## 🧪 Testing\n\nThe library includes comprehensive test coverage:\n\n```bash\n# Run all tests\ndotnet test\n\n# Run with detailed output\ndotnet test --logger \"console;verbosity=detailed\"\n```\n\nTests require a Guardian API key stored in user secrets:\n```bash\ndotnet user-secrets set \"GuardianApiKey\" \"your-api-key-here\"\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n*This is an unofficial library and is not affiliated with The Guardian.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarrball%2Fguardianclient.net","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarrball%2Fguardianclient.net","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarrball%2Fguardianclient.net/lists"}