Documentation · Screening API

Tuning the matcher

Which parameters change a match result, what each scoring method does, where the matcher falls short, and which inputs help most.

Matching runs in two stages: candidates are gathered from the collection by name words and IMO number, then each is scored. Three request parameters change the outcome.

Parameters

algorithm

The scoring method. standard (the default) weighs the name with birth date, country, IMO number and entity type. name-only scores the name alone; the other features are still reported but do not change the score. best is accepted and means the current default. List the methods, their features and the default with:

curl "https://api.crownintelligence.net/api/algorithms"

import requests

info = requests.get("https://api.crownintelligence.net/api/algorithms", timeout=30).json()
print("default:", info["default"], "threshold:", info["threshold"])
for a in info["algorithms"]:
    print(a["name"], "-", a["description"])

threshold

The score at which match becomes true, from 0 to 1. The default is 0.75. Results below the threshold are still returned (up to limit), so you can see near misses; only the flag changes. Raise it to reduce alerts on common names; lower it if you would rather review more.

limit

Results per query, 1 to 50, default 5. Each register's record is returned separately, so one party listed by several registers can fill several places; raise limit if you want to see beyond them.

Scoring methods

standard aligns each word of your name with the closest word of the record's name or aliases (Jaro-Winkler similarity), weights longer words more, and discounts record words you did not mention. It then adds or subtracts for birth date, country, IMO number and entity type. name-only uses the name alignment alone; use it for lists where the other details are unreliable, and expect more alerts. Exact effects and constants are on Matching algorithms.

Feature weights

The effect of each feature is fixed for each method; requests cannot change them. If you need different behaviour, choose the method, adjust the threshold, or post-process the features in each result with your own rules.

Limitations

• No transliteration. Names in Cyrillic, Arabic or Chinese script are compared as written. Records often carry Latin-script aliases; send both scripts when you have them.
• No phonetic matching. Spelling variants are caught only when they are close letter by letter.
• No nickname or name-order knowledge. Name words are aligned in any order, but "Bill" does not match "William".
• Company legal forms count as words. "Example Trading LLC" against "Example Trading Limited" loses a little for the differing word.
• Identifiers. Only IMO numbers are compared; registration, tax and LEI numbers are not yet scored.
• Short names. A one-word query against a longer name is scored down, so mononyms and short company names need other details to reach the threshold.

Selecting your input data

• Use the most specific schema you know.
• Send every name and alias you hold, in every script.
• Send the birth date at whatever precision you have; a year still helps.
• Send nationality, residence or country of registration as ISO codes.
• For vessels, always send the IMO number.
• Narrow the candidates with the collection, topics and register filters rather than by raising the threshold alone.

Further reading

• Matching algorithms: features, effects and constants.
• The US Treasury's Sanctions List Search, a public name-matching tool for the OFAC lists.

Last updated 2026-10-03