search

Documentation

Index

• func DebugSimilarity[Q any, I any](w io.Writer, query Entity[Q], index Entity[I]) float64
• func Similarity[Q any, I any](query Entity[Q], index Entity[I]) float64
• type Address
  • func (a Address) Format() string
• type Affiliation
• type Aircraft
• type AircraftType
• type Business
• type Client
  • func NewClient(httpClient *http.Client, baseAddress string) Client
• type ContactInfo
• type CryptoAddress
• type Entity
  • func (e Entity[T]) Normalize() Entity[T]
• type EntityType
• type Gender
• type GovernmentID
• type GovernmentIDType
• type HistoricalInfo
• type ListInfoResponse
• type MockClient
  • func NewMockClient() *MockClient
  • func (c *MockClient) ListInfo(ctx context.Context) (ListInfoResponse, error)
  • func (c *MockClient) Normalize()
  • func (c *MockClient) SearchByEntity(ctx context.Context, query Entity[Value], opts SearchOpts) (SearchResponse, error)
• type Organization
• type Person
• type PreparedFields
• type SanctionsInfo
• type SearchOpts
• type SearchResponse
• type SearchedEntity
• type SourceList
• type Value
• type Vessel
• type VesselType

Functions

func DebugSimilarity

func DebugSimilarity[Q any, I any](w io.Writer, query Entity[Q], index Entity[I]) float64

DebugSimilarity does the same as Similarity, but logs debug info to w.

func Similarity

func Similarity[Q any, I any](query Entity[Q], index Entity[I]) float64

Similarity calculates a match score between a query and an index entity.

Types

type Address

type Address struct {
	Line1      string `json:"line1"`
	Line2      string `json:"line2"`
	City       string `json:"city"`
	PostalCode string `json:"postalCode"`
	State      string `json:"state"`
	Country    string `json:"country"` // ISO-3166 code

	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`
}

Address is a struct which represents any physical location

TODO(adam): Should probably adopt something like libpostal's naming https://github.com/openvenues/libpostal?tab=readme-ov-file#parser-labels

Or OpenSanctions https://www.opensanctions.org/reference/#schema.Address

func (Address) Format

func (a Address) Format() string

type Affiliation

type Affiliation struct {
	EntityName string `json:"entityName"`
	Type       string `json:"type"` // e.g., "Linked To", "Subsidiary Of", "Owned By"
	Details    string `json:"details,omitempty"`
}

type Aircraft

type Aircraft struct {
	Name         string       `json:"name"`
	AltNames     []string     `json:"altNames"`
	Type         AircraftType `json:"type"`
	Flag         string       `json:"flag"` // ISO-3166 // TODO(adam):
	Built        *time.Time   `json:"built"`
	ICAOCode     string       `json:"icaoCode"` // ICAO aircraft type designator
	Model        string       `json:"model"`
	SerialNumber string       `json:"serialNumber"`
}

type AircraftType

type AircraftType string

var (
	AircraftTypeUnknown AircraftType = "unknown"
	AircraftCargo       AircraftType = "cargo"
)

type Business

type Business struct {
	Name          string         `json:"name"`
	AltNames      []string       `json:"altNames"`
	Created       *time.Time     `json:"created"`
	Dissolved     *time.Time     `json:"dissolved"`
	GovernmentIDs []GovernmentID `json:"governmentIDs"`
}

type Client

type Client interface {
	ListInfo(ctx context.Context) (ListInfoResponse, error)
	SearchByEntity(ctx context.Context, entity Entity[Value], opts SearchOpts) (SearchResponse, error)
}

func NewClient

func NewClient(httpClient *http.Client, baseAddress string) Client

type ContactInfo

type ContactInfo struct {
	EmailAddresses []string `json:"emailAddresses"`
	PhoneNumbers   []string `json:"phoneNumbers"`
	FaxNumbers     []string `json:"faxNumbers"`
	Websites       []string `json:"websites"`
}

type CryptoAddress

type CryptoAddress struct {
	Currency string `json:"currency"`
	Address  string `json:"address"`
}

CryptoAddress

&cryptoAddress=XBT:x123456

type Entity

type Entity[T Value] struct {
	Name   string     `json:"name"`
	Type   EntityType `json:"entityType"`
	Source SourceList `json:"sourceList"`

	// SourceID is the source data's identifier.
	SourceID string `json:"sourceID"`

	Person       *Person       `json:"person"`
	Business     *Business     `json:"business"`
	Organization *Organization `json:"organization"`
	Aircraft     *Aircraft     `json:"aircraft"`
	Vessel       *Vessel       `json:"vessel"`

	Contact   ContactInfo `json:"contact"`
	Addresses []Address   `json:"addresses"`

	CryptoAddresses []CryptoAddress `json:"cryptoAddresses"`

	Affiliations   []Affiliation    `json:"affiliations"`
	SanctionsInfo  *SanctionsInfo   `json:"sanctionsInfo"`
	HistoricalInfo []HistoricalInfo `json:"historicalInfo"`

	PreparedFields PreparedFields `json:"-"`

	SourceData T `json:"sourceData"` // Contains all original list data with source list naming
}

func (Entity[T]) Normalize

func (e Entity[T]) Normalize() Entity[T]

type EntityType

type EntityType string

var (
	EntityPerson       EntityType = "person"
	EntityBusiness     EntityType = "business"
	EntityOrganization EntityType = "organization"
	EntityAircraft     EntityType = "aircraft"
	EntityVessel       EntityType = "vessel"
)

type Gender

type Gender string

var (
	GenderUnknown Gender = "unknown"
	GenderMale    Gender = "male"
	GenderFemale  Gender = "female"
)

type GovernmentID

type GovernmentID struct {
	Type       GovernmentIDType `json:"type"`
	Country    string           `json:"country"` // ISO-3166 // TODO(adam):
	Identifier string           `json:"identifier"`
}

type GovernmentIDType

type GovernmentIDType string

var (
	GovernmentIDPassport            GovernmentIDType = "passport"
	GovernmentIDDriversLicense      GovernmentIDType = "drivers-license"
	GovernmentIDNational            GovernmentIDType = "national-id"
	GovernmentIDTax                 GovernmentIDType = "tax-id"
	GovernmentIDSSN                 GovernmentIDType = "ssn"
	GovernmentIDCedula              GovernmentIDType = "cedula"
	GovernmentIDCURP                GovernmentIDType = "curp"
	GovernmentIDCUIT                GovernmentIDType = "cuit"
	GovernmentIDElectoral           GovernmentIDType = "electoral"
	GovernmentIDBusinessRegisration GovernmentIDType = "business-registration"
	GovernmentIDCommercialRegistry  GovernmentIDType = "commercial-registry"
	GovernmentIDBirthCert           GovernmentIDType = "birth-certificate"
	GovernmentIDRefugee             GovernmentIDType = "refugee-id"
	GovernmentIDDiplomaticPass      GovernmentIDType = "diplomatic-passport"
	GovernmentIDPersonalID          GovernmentIDType = "personal-id"
)

type HistoricalInfo

type HistoricalInfo struct {
	Type  string    `json:"type"`  // e.g., "Former Name", "Previous Flag"
	Value string    `json:"value"` // The historical value
	Date  time.Time `json:"date,omitempty"`
}

type ListInfoResponse

type ListInfoResponse struct {
	Lists      map[string]int    `json:"lists"`
	ListHashes map[string]string `json:"listHashes"`

	StartedAt time.Time `json:"startedAt"`
	EndedAt   time.Time `json:"endedAt"`

	// Version is the version of Watchman that returned results.
	Version string `json:"version"`
}

type MockClient

type MockClient struct {
	Err error

	ListInfoResponse ListInfoResponse

	Index    []Entity[Value]
	Searches []Entity[Value]
	// contains filtered or unexported fields
}

func NewMockClient

func NewMockClient() *MockClient

func (*MockClient) ListInfo

func (c *MockClient) ListInfo(ctx context.Context) (ListInfoResponse, error)

func (*MockClient) Normalize

func (c *MockClient) Normalize()

func (*MockClient) SearchByEntity

func (c *MockClient) SearchByEntity(ctx context.Context, query Entity[Value], opts SearchOpts) (SearchResponse, error)

type Organization

type Organization struct {
	Name          string         `json:"name"`
	AltNames      []string       `json:"altNames"`
	Created       *time.Time     `json:"created"`
	Dissolved     *time.Time     `json:"dissolved"`
	GovernmentIDs []GovernmentID `json:"governmentIDs"`
}

Organization

TODO(adam): https://www.opensanctions.org/reference/#schema.Organization

type Person

type Person struct {
	Name      string     `json:"name"`
	AltNames  []string   `json:"altNames"`
	Gender    Gender     `json:"gender"`
	BirthDate *time.Time `json:"birthDate"`
	DeathDate *time.Time `json:"deathDate"`
	Titles    []string   `json:"titles"`

	GovernmentIDs []GovernmentID `json:"governmentIDs"`
}

type PreparedFields

type PreparedFields struct {
	Name     string
	AltNames []string

	// NameFields and AltNameFields are precomputed slices of significant terms
	NameFields    []string
	AltNameFields [][]string

	Contact ContactInfo
}

type SanctionsInfo

type SanctionsInfo struct {
	Programs    []string `json:"programs"`    // e.g., "SDGT", "IRGC"
	Secondary   bool     `json:"secondary"`   // Subject to secondary sanctions
	Description string   `json:"description"` // Additional details
}

type SearchOpts

type SearchOpts struct {
	Limit    int
	MinMatch float64
}

type SearchResponse

type SearchResponse struct {
	Entities []SearchedEntity[Value] `json:"entities"`
}

type SearchedEntity

type SearchedEntity[T any] struct {
	Entity[T]

	Match float64 `json:"match"`

	// Debug is an optional base64 encoded humand-readable field that contains
	// detailed field-level match scores and weight adjustments.
	//
	// Adding ?debug to /v2/search will populated this field, but more memory
	// will be used for each request.
	//
	// The format will change over time and should not be parsed by machines.
	Debug string `json:"debug,omitempty"`
}

type SourceList

type SourceList string

var (
	SourceAPIRequest SourceList = "api-request"

	SourceEUCSL  SourceList = "eu_csl"
	SourceUKCSL  SourceList = "uk_csl"
	SourceUSCSL  SourceList = "us_csl"
	SourceUSOFAC SourceList = "us_ofac"
)

type Value

type Value interface{}

type Vessel

type Vessel struct {
	Name                   string     `json:"name"`
	AltNames               []string   `json:"altNames"`
	IMONumber              string     `json:"imoNumber"`
	Type                   VesselType `json:"type"`
	Flag                   string     `json:"flag"` // ISO-3166 // TODO(adam):
	Built                  *time.Time `json:"built"`
	Model                  string     `json:"model"`
	Tonnage                int        `json:"tonnage"`
	MMSI                   string     `json:"mmsi"` // Maritime Mobile Service Identity
	CallSign               string     `json:"callSign"`
	GrossRegisteredTonnage int        `json:"grossRegisteredTonnage"`
	Owner                  string     `json:"owner"`
}

Vessel

TODO(adam): https://www.opensanctions.org/reference/#schema.Vessel

type VesselType

type VesselType string

var (
	VesselTypeUnknown VesselType = "unknown"
	VesselTypeCargo   VesselType = "cargo"
)