A C# SDK for the NewsCatcher News API v3, offering full .NET integration, async/await support, and comprehensive exception handling with platform-specific optimizations.

Requirements

  • .NET Core >=1.0
  • .NET Framework >=4.6
  • Mono/Xamarin >=vNext

Installation

Using the .NET CLI

dotnet add package Newscatcherapi.Net

Using NuGet Package Manager Console

Install-Package Newscatcherapi.Net

Using Package Manager UI in Visual Studio

  1. Right-click on your project in Solution Explorer.
  2. Select “Manage NuGet Packages”.
  3. Search for “Newscatcherapi.Net”.
  4. Click Install.

Core features

Initialize client

using Newscatcherapi.Net.Client;

var client = new NewscatcherClient();
client.SetApiKey("YOUR_API_KEY");

Search articles

// Regular search
try
{
    var result = await client.Search.Get(
        q: "technology",
        lang: "en",
        includeNlpData: true
    );
    Console.WriteLine($"Found {result.TotalHits} articles");
}
catch (ApiException e)
{
    Console.WriteLine($"Error: {e.ErrorCode} - {e.Message}");
}

// Clustered search
var clusterResults = await client.Search.Get(
    q: "AI technology",
    lang: "en",
    clusteringEnabled: true,
    clusteringThreshold: 0.6,
    includeNlpData: true
);

Latest headlines

var headlines = await client.LatestHeadlines.Get(
    lang: "en",
    countries: "US",
    clusteringEnabled: true,
    includeNlpData: true
);
var authorArticles = await client.Authors.Get(
    authorName: "Sam Altman",
    includeNlpData: true
);

Similar articles

var similar = await client.SearchSimilar.Get(
    q: "SpaceX launch",
    includeNlpData: true
);

Get sources

var sources = await client.Sources.Get(
    lang: "en"
);

Check subscription

var subscription = await client.Subscription.Get();

Advanced features

Error handling

The SDK provides detailed error information through ApiException:

try
{
    var result = await client.Search.Get(q: "tech news");
}
catch (ApiException e)
{
    Console.WriteLine($"Error code: {e.ErrorCode}");
    Console.WriteLine($"Error content: {e.ErrorContent}");
    Console.WriteLine($"Headers: {e.Headers}");
    Console.WriteLine($"Response details: {e.Message}");
}
catch (Exception e)
{
    Console.WriteLine($"General error: {e.Message}");
}

Cancellation support

All async operations support cancellation tokens:

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(5)); // 5-second timeout

try
{
    var result = await client.Search.GetAsync(
        q: "tech",
        cancellationToken: cts.Token
    );
}
catch (OperationCanceledException)
{
    Console.WriteLine("Request timed out");
}

Utilities

Rate limit handler

public static class RateLimitHandler
{
    public static async Task<T> WithRetry<T>(
        Func<Task<T>> operation,
        int maxRetries = 3,
        int baseDelay = 1000)
    {
        for (int i = 0; i < maxRetries; i++)
        {
            try
            {
                return await operation();
            }
            catch (ApiException e) when (e.ErrorCode == 429)
            {
                if (i == maxRetries - 1)
                    throw;

                var delay = baseDelay * Math.Pow(2, i);
                await Task.Delay((int)delay);
            }
        }
        throw new Exception("Max retries exceeded");
    }
}

// Usage
var result = await RateLimitHandler.WithRetry(async () =>
    await client.Search.Get(q: "tech")
);

Pagination handler

public static class PaginationHandler
{
    public static async Task<List<Article>> GetAllResults(
        NewscatcherClient client,
        string query,
        int maxPages = 5)
    {
        var results = new List<Article>();

        for (int page = 1; page <= maxPages; page++)
        {
            var response = await client.Search.Get(
                q: query,
                page: page,
                pageSize: 100
            );

            results.AddRange(response.Articles);

            if (page >= response.TotalPages)
                break;
        }

        return results;
    }
}

// Usage
var allArticles = await PaginationHandler.GetAllResults(
    client,
    "AI technology",
    maxPages: 2
);

HTTP client configuration

var config = new Configuration
{
    UserAgent = "CustomUserAgent/1.0",
    Timeout = 30000, // 30 seconds
    BasePath = "https://your-proxy.com/v3-api.newscatcherapi.com"
};

var client = new NewscatcherClient(config);

Additional resources

Was this page helpful?