Enhance (GET)

GEThttps://kg.diffbot.com/kg/v3/enhance

Enrich a person or organization record with partial data input.

Enhance is an enrichment API to find a person or organization using partial data as input. Enhance scores several candidates against the submitted query and returns the best match. More information in the query helps Enhance models estimate with more confidence and will typically result in better matches and a higher score for the matches.

A minimal request specifies the entity type, a name, and optionally a location:

GET /kg/v3/enhance?type={type}&name={name}&location={address}

Where {type} is either Person or Organization, {name} is the name of the entity and {address} is a complete or partial address of the entity.

You can specify more/other input, such as url or employer. The supported parameters are listed below.

Scoring and Threshold

Enhance uses a cut-off based on the F2 score by default, erring on the side of recall. However, you can control the threshold using the threshold parameter depending on your application's specific needs.

Enhance also returns at most 1 result by default. You can control this with the size parameter. Note that this can cause proportionately more credits to be used if there are more matches returned.

(size parameter is not supported for combine requests.)

Refresh mode

It is possible that some of the origins for the results have not been revisited by our crawler in a while. If you need fresher data than what's available, you can force a refresh with the refresh=true parameter. Any origins that have not been crawled in the last 30 days will be recrawled and merged with the entity found in the Knowledge Graph.

WARNING

The refresh parameter should not be used by default. Refreshing origins in general and refreshing all origins in particular can be a time-consuming request as Enhance needs to recrawl pages before merging them into the result. If you need only specific origins refreshed, you can also control that using the refreshOrigins parameter.

Search mode

By default, Enhance returns entities in the Knowledge Graph. It can also search the web for the queried entity with the search=true parameter. Search results are scored for a match and merged with the entity found in the Knowledge Graph.

WARNING

The search parameter should not be used by default. It can be very slow and the quality of results are usually variable external websites. In our experience, this parameter is not usually necessary.

Example

REQUEST

curl --request GET \
  --url 'https://kg.diffbot.com/kg/v3/enhance?token=<DIFFBOT_TOKEN>&type=Organization&name=Diffbot&filter=%24.name%3B%24.diffbotUri%3B%24.homepageUri%3B%24.twitterUri%3B%24.nbEmployees' \
  --header 'Accept: application/json'

RESPONSE

{
  "version": 3,
  "hits": 1,
  "kgversion": "477",
  "request_ctx": {
    "query": {
      "type": "Organization",
      "name": "Diffbot"
    },
    "query_ctx": {
      "search": "OFF"
    }
  },
  "data": [
    {
      "score": 0.7037951087035074,
      "esscore": 1840.4940185546875,
      "entity": {
        "twitterUri": "twitter.com/diffbot",
        "name": "Diffbot",
        "diffbotUri": "http://diffbot.com/entity/EYX1i02YVPsuT7fPLUYgRhQ",
        "homepageUri": "diffbot.com",
        "nbEmployees": 40
      },
      "errors": []
    }
  ],
  "errors": []
}