- Page restrictions apply
- Added by Bradley, last edited by Bradley on Dec 27, 2011 (view change)
Introduction
Resolve is an entity resolution API that makes partial records complete, matches one entity against another, and assists in de-duping and normalizing datasets. The idea behind Resolve is very straightforward: you tell us what you know about an entity, and we tell you everything Factual knows about it. Resolve accepts fragments of an entity and returns the matching entity in its entirety. This API is designed to do a number of things that make data engineering tasks easier:
Try Resolve with our interactive demo. |
|
ย
How Does Resolve Differ from Search?
On the surface Resolve may seem very similar to Search, but addresses very different use case: it's all about entity resolution and disambiguation:
- Search is designed to return multiple items for subsequent disambiguation (usually when a person selects a blue link in the result set), while Resolve performs the disambiguation automatically. We've designed Factual Resolve for machine-to-machine communication, allowing your service can talk to ours continuously, helping to normalize and enrich your data, without the need for ongoing human intervention.
- Search is promiscuous: it wants to return the best possible results despite the quality of a match, as it knows a human is on the other end to disambiguate or re-query. Resolve looks at an absolute rather than the relative quality of the result set, based on your structured input parameters
- Search is the 'S' in SEO: search results are traditionally biased by a metric other than matching attribute values; Resolve performs a like-for-like comparison against data entities without external bias
In Beta
We have a few partners helping us test Resolve in production, but this is a beta release with all the usual caveats: we'll be tweaking the service and weightings and addressing an increasing number edge cases.
Resolve requires a Factual V3 key. New users and those on V2 should request a key from us here
Debug Dashboard
You can try Resolve with a graphical interface here.
Basic Syntax
Pass what you know to Factual Resolve via a GET request, with the attributes included as JSON-encoded key/value pairs.
Examples
We've remove URL encoding from these examples for clarity, but remember to URL encode the entirety of your JSON string before calling.
Run this example in Apigee
Run this example in Apigee
Parameters
Required Parameters
Parameter Name | Description | Example |
|---|---|---|
KEY | Your API Key. Factual API key documentation is here. The KEY parameter name and value are both case-sensitive | KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI |
values | A JSON hash of key value pairs representing the data that will be resolved against. | values={"name":"McDonalds","address":"10451 Santa Monica Blvd","locality":"Los Angeles","region":"CA"} |
We accept any Global Local parameters in most combinations; some combinations of parameters will be encountered more frequently than others, and have therefore consumed the respective proportion of our beta development efforts.
Resolve is designed to work with whatever you throw at it, but the more parameters you provide, the better we can resolve your attributes to an entity. Give us what you got!
Optional Parameters
There are no optional parameters for the Resolve API call.
Responses
Successful Responses
The resolve API response object is similar to the read API. The difference is that any returned entities will have the two specific attributes added: resolved and similarity. These attributes are explained below.
Response Components
object | description |
|---|---|
version | Version of the API that generated this response |
response | Will return the number of rows in the included data packet, the data, and (if requested) the _ total number of rows_ conforming to the filters specified by this request. |
response.data | The place(s) that match your request. |
response.data.resolved | true if Factual believes this is the exact entity with no ambiguity. False if it is a very good candidiate (high similarity) but cannot be adequately disambiguated from another very good candidate. |
response.data.similarity | A value between 0.0 (low) and 1.0 (high) that represents how similar the result is to what was requested. |
response.included_rows | The number of rows contained in the data array. In other words, the length of the data array. |
Successful Call, Resolved
In this example, Resolve has determined that a single, suitable candidate meets the criteria you passed to the platform with the flag resolved=true. The resolved entity is always provided first (we also return other candidates for debugging purposes, set with the flag resolved=false):
Successful Call, Unresolved
In this example, Resolve has found a number of candidates that may match your inputs, but has been unable to identify an unequivocal match. In these instances we return the top candidates we found with resolved=false. These entities are returned for debugging purposes, and allows you and Factual to determine whether there may be an error in the resolution algo, the data, or the input parameters.
Successful Call, Unresolved, No Candidates
In this example, Resolve has found no candidates it can even match against.
Error Responses
Resolve Error Messages and Causes
In addition to general Factual API errors, the following errors may be returned in response to GET requests:
HTTP Error code | Factual Error Type | Message | Cause |
|---|---|---|---|
400 | InvalidJsonArgument | Parameter 'values' contains an error in it's JSON syntax. For documentation, please see: developer.factual.com | values parameter is expressed using invalid JSON |