interpolclient

README

go-interpol-client

A small Go client for INTERPOL's public Red Notices search API — free, keyless.

Install

go get github.com/olehmushka/go-interpol-client

Usage

c := interpolclient.New(nil, interpolclient.WithUserAgent("myapp/1.0 (contact@example.com)"))

result, err := c.SearchRedNotices(ctx, interpolclient.Query{
    Surname:  "Doe",
    Forename: "John",
})
if err != nil {
    // real failure (network, non-200, bad response shape)
}
for _, n := range result.Notices {
    // n.Forename, n.Name
}

Scope

This client covers the transport layer only: build a query, get back the raw notices INTERPOL returns. It deliberately does not score or interpret the results (e.g. "is this a match for person X, and how confident") — that is application-specific business logic that belongs in the calling application, not something a generic client to this API should decide.

Notes

Built on go-govapi-core for the HTTP client and User-Agent conventions. The request/response shapes mirror an already-shipped, already-verified integration against this same live endpoint in go-oikumenea's internal/hermenea/watchlist/interpol.go (its D-Watchlists / M34 live-lookup connector) — this package is that integration's HTTP layer, extracted and generalized.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package interpolclient is a small client for INTERPOL's public Red Notices search API (https://ws-public.interpol.int/notices/v1/red) — free, keyless.

This package covers the transport layer only: build a query, get back the raw notices INTERPOL returns. It deliberately does not score or interpret the results (e.g. "is this a match for person X") — that is application-specific business logic, not something a generic client to this API should decide for its caller.

The request/response shapes here mirror an already-shipped, already-verified integration against this same live endpoint: https://github.com/olehmushka/go-oikumenea/blob/main/internal/hermenea/watchlist/interpol.go (go-oikumenea's D-Watchlists / M34 live-lookup connector) — this package is that integration's HTTP layer, extracted and generalized.

Index

• Constants
• type Client
  • func New(httpClient *http.Client, opts ...Option) *Client
  • func (c *Client) SearchRedNotices(ctx context.Context, q Query) (SearchResult, error)
• type Notice
• type Option
  • func WithBaseURL(baseURL string) Option
  • func WithUserAgent(userAgent string) Option
• type Query
• type SearchResult

Constants

const DefaultBaseURL = "https://ws-public.interpol.int/notices/v1/red"

DefaultBaseURL is INTERPOL's public Red Notices endpoint.

const DefaultUserAgent = "go-interpol-client/0.1 (+https://github.com/olehmushka/go-interpol-client)"

DefaultUserAgent identifies this client when UserAgentEnv is unset.

const UserAgentEnv = "INTERPOL_CLIENT_USER_AGENT"

UserAgentEnv lets an operator override the outbound User-Agent with their own contact, the same convention go-govapi-core's ResolveUserAgent expects.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an INTERPOL Red Notices search client. The zero value is not usable — construct one with New.

func New

func New(httpClient *http.Client, opts ...Option) *Client

New constructs an INTERPOL client. httpClient nil defaults to a client bounded by defaultTimeout (govapicore.NewHTTPClient) — a Red Notices search is a small, single-request lookup, not a streaming download.

func (*Client) SearchRedNotices

func (c *Client) SearchRedNotices(ctx context.Context, q Query) (SearchResult, error)

SearchRedNotices issues one search request against the Red Notices endpoint.

type Notice

type Notice struct {
	Forename string
	Name     string
}

Notice is one Red Notice entry as INTERPOL's API returns it — only the fields this client's callers need (the full response carries considerably more).

type Option

type Option func(*Client)

Option configures a Client constructed via New.

func WithBaseURL

func WithBaseURL(baseURL string) Option

WithBaseURL overrides DefaultBaseURL — e.g. to point at a test double.

func WithUserAgent

func WithUserAgent(userAgent string) Option

WithUserAgent overrides the default/env-resolved User-Agent.

type Query

type Query struct {
	Surname  string
	Forename string
	// ResultsPerPage <= 0 uses defaultResultsPerPage.
	ResultsPerPage int
}

Query is a Red Notices search request. Surname is required — INTERPOL's own `name` parameter is the surname/family name; an empty Surname returns an empty SearchResult without a request (mirrors go-oikumenea's splitName-derived "no surname, no lookup" behavior).

type SearchResult

type SearchResult struct {
	Total   int
	Notices []Notice
}

SearchResult is a Red Notices search response.