OPopensanctions
Matching

Query by example matcher

Changed on

Match entities based on a complex set of criteria, like name, date of birth and nationality of a person. This works by submitting an entity formatted like those returned by the API.

Tutorials:

For example, the following would be a valid query:

"queries": {
    "q": {
        "schema": "Person",
        "properties": {
            "name": ["John Doe"],
            "birthDate": ["1975-04-21"],
            "nationality": ["us"]
        }
    }
}

The value for q can be chosen freely to correlate the result on the client side when the request is returned. The response will be given for the submitted example like this:

"responses": {
    "q": {
        "query": {},
        "results": [...]
    }
}

While more than one query can theoretically be submitted per request, batching is discouraged for performance and scalability reasons.

The precision of the results will be dependent on the amount of detail submitted with each example. The following properties are most helpful for particular types:

  • Person: name, birthDate, nationality, idNumber, address
  • Organization: name, country, registrationNumber, address
  • Company: name, jurisdiction, registrationNumber, address, incorporationDate
post/match/{dataset}

Request

  • Base URL
    https://api.opensanctions.org (the document declares no server; this is the origin it was published from)
  • URL
    https://api.opensanctions.org/match/{dataset}
  • Auth
    none declared

Path parameters

datasetstring required

Data source or collection name to scope the query to.

Example:default

Query parameters

limitinteger
thresholdnumber
cutoffnumber
algorithmstring
include_datasetstring[]
exclude_schemastring[]
exclude_datasetstring[]
topicsstring[]
changed_sincestring nullable
exclude_entity_idsstring[]

The entity IDs supplied here do not have to be canonical. Supplying any of the referents of a merged entity will exclude that entity. This parameter may be useful for example to exclude false-positive matches that have been decided upon by a human.

Request body

weightsobject
configobject

Algorithm-specific configuration parameters.

queriesobject required

Example request

{
  "weights": {
    "name_literal": 0.8
  },
  "config": {
    "nm_number_mismatch": 0.4
  }
}

Response

Successful Response

responsesobject required
limitinteger required

Example response

{
  "limit": 5
}

Changes

  • c5a282ece45dRevision changes
    • warning

      removed the optional property //// from the response with the status

    • info

      removed subschema #1 subschema #2 from the //// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //////// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //////// response property anyOf list for the response status

    • info

      removed subschema #1 subschema #2 from the //////// response property anyOf list for the response status

  • 024572c7ad35Revision changes
    • breaking

      for the query request parameter algorithm, default value was changed from logic-v1 to best

    • breaking

      for the query request parameter cutoff, default value was changed from 0.5 to 0.7

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property //// from the response with the status

    • info

      added the new optional query request parameter exclude_entity_ids

    • info

      added the new optional request property

    • info

      query request parameter cutoff was deprecated

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      the response property //// became required for the status

    • info

      the response's property default value false was removed for the status

    • info

      added the required property //// to the response with the status