A Go SDK for the NewsCatcher News API v3, featuring idiomatic Go patterns, context support, and efficient error handling with strong type safety.

​
Requirements

  • Go 1.18 or higher

​
Installation

Add the SDK to your project using Go modules: 
go get github.com/konfig-dev/newscatcher-go-sdk

​
Core features

​
Initialize client

import (
    "fmt"
    newscatcherapi "github.com/konfig-dev/newscatcher-go-sdk"
)

configuration := newscatcherapi.NewConfiguration()
configuration.SetApiKey("YOUR_API_KEY")
client := newscatcherapi.NewAPIClient(configuration)

​
Search articles

// Regular search
request := client.SearchApi.Get(context.Background())
request.Q("technology")
request.Lang("en")
request.IncludeNlpData(true)

result, response, err := request.Execute()
if err != nil {
    fmt.Printf("Error: %v\n", err)
    return
}

// Clustered search
clusterRequest := client.SearchApi.Get(context.Background())
clusterRequest.Q("AI technology")
clusterRequest.Lang("en")
clusterRequest.ClusteringEnabled(true)
clusterRequest.ClusteringThreshold(0.6)
clusterRequest.IncludeNlpData(true)

clusterResult, response, err := clusterRequest.Execute()

​
Latest headlines

request := client.LatestHeadlinesApi.Get(context.Background())
request.Lang("en")
request.Countries("US")
request.ClusteringEnabled(true)
request.IncludeNlpData(true)

headlines, response, err := request.Execute()

request := client.AuthorsApi.Get(context.Background(), "Sam Altman")
request.IncludeNlpData(true)

authorArticles, response, err := request.Execute()

​
Similar articles

request := client.SearchSimilarApi.Get(context.Background())
request.Q("SpaceX launch")
request.IncludeNlpData(true)

similar, response, err := request.Execute()

​
Get sources

request := client.SourcesApi.Get(context.Background())
request.Lang("en")

sources, response, err := request.Execute()

​
Check subscription

subscription, response, err := client.SubscriptionApi.Get(context.Background()).Execute()

​
Advanced features

​
HTTP response handling

The SDK provides detailed HTTP response information: 
request := client.SearchApi.Get(context.Background())
request.Q("tech")

result, response, err := request.Execute()
if err != nil {
    fmt.Printf("Error: %v\n", err)
    fmt.Printf("Response: %v\n", response)
    fmt.Printf("Status code: %v\n", response.StatusCode)
    fmt.Printf("Headers: %v\n", response.Header)
    return
}

​
Context support

All API operations support context for timeout and cancellation: 
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

request := client.SearchApi.Get(ctx)
result, response, err := request.Execute()

​
Error handling

The SDK uses GenericOpenAPIError for comprehensive error handling: 
request := client.SearchApi.Get(context.Background())
request.Q("tech news")

result, response, err := request.Execute()
if err != nil {
    if apiError, ok := err.(*newscatcherapi.GenericOpenAPIError); ok {
        fmt.Printf("Error body: %v\n", string(apiError.Body()))
        fmt.Printf("Error model: %v\n", apiError.Model())
    }
    fmt.Printf("Full error: %v\n", err)
    return
}

​
Utilities

​
Rate limit handler

func withRetry(operation func() error, maxRetries int, delay time.Duration) error {
    var lastErr error
    for i := 0; i < maxRetries; i++ {
        err := operation()
        if err == nil {
            return nil
        }

        if apiErr, ok := err.(*newscatcherapi.GenericOpenAPIError); ok {
            // Check if it's a rate limit error
            if strings.Contains(string(apiErr.Body()), "429") {
                time.Sleep(delay * time.Duration(math.Pow(2, float64(i))))
                lastErr = err
                continue
            }
        }
        return err
    }
    return fmt.Errorf("max retries exceeded: %v", lastErr)
}

// Usage
request := client.SearchApi.Get(context.Background())
request.Q("tech")

err := withRetry(func() error {
    _, _, err := request.Execute()
    return err
}, 3, time.Second)

​
Pagination handler

func getAllResults(client *newscatcherapi.APIClient, query string, maxPages int) ([]Article, error) {
    var results []Article

    for page := 1; page <= maxPages; page++ {
        request := client.SearchApi.Get(context.Background())
        request.Q(query)
        request.Page(page)
        request.PageSize(100)

        response, _, err := request.Execute()
        if err != nil {
            return nil, err
        }

        results = append(results, response.Articles...)

        if page >= response.TotalPages {
            break
        }
    }

    return results, nil
}

​
Additional resources