API FAQ

Use POST /api/match to decide whether a party is listed: it scores every candidate on name, birth date, country, IMO number and type and explains the score. Use GET /api/search for look-ups and interfaces: it lists records that contain your words, unscored.

To keep them fast and small. Fetch /api/entity/<id> for a record with its listings and the other registers that name the same party, or the merged entity for the combined view.

Up to 20 queries per match or reconcile request, each with up to 50 results. Queries beyond 20 are ignored.

A query needs at least one name or an IMO number. The error field says what was missing, and the other queries in the batch still run.

Each register's entry is its own record, so a person on five lists can give five results. Records we have linked share merged_entity.

Results reflect the records loaded at the time of the request. Some read-only answers (search, facets, sources, programmes, countries) are cached for up to 10 minutes; match results are not cached.

No quota is enforced today. The service can apply a per-address request limit and answers 429 with Retry-After when it does; see Request limits.

• Batch up to 20 parties per match request.
• Do not re-screen unchanged parties against an unchanged collection: compare the collection version from /api/catalog first.
• Back off on 429 and 503 and retry later rather than at once.
• For large books, consider the bulk files.