Getting started

POST /v1/places/match

The Match API v1 uses fuzzy logic with various sets of rules to match and append to your data.

The difference between Search API and Match API is that Search API returns exact results from filters, whereas Match API matches your entities to the Data Axle database.

curl https://qa.api.data-axle.com/v1/places/match -d '{
  "identifiers": {
    "name": "Best Business Ever",
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98103"
  }
}'

The response includes a persistent infogroup_id along with appended attributes:

{
  "document": {
    "infogroup_id": "939010853",
    "rules": ["address"],
    "score": 0.90,
    "attributes": {
      "name": "Best Business Ever",
      "street": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98103",
      ...
    }
  }
}

• GET or POST can be used.
• By default, one match is returned. Set the limit option to retrieve multiple matches.
• All available fields are included in the output. This can be changed with the fields option.
• If a match is not found, a null document is returned.

Parameters

Identifiers

The fields you can submit for matching are:

See the rule descriptions for which fields are required for each rule to match.

reference_id is not used for matching, but is an optional field that can be used to reference requests using an ID from your own system. It will be returned with the results of batch requests.

Rules

Rules are automatically selected based on the data provided.

Records that only match a single rule will only be returned if the rule is marked as "high confidence". If only one rule was run, such as when only an address is provided, address matches will be included in the result.

Score

Match scores are provided to make it easier to compare the similarity of the input to the matched record. Records are scored 0-1, with a higher score indicating greater similarity.

Different use cases may benefit from different score threshold considerations. We recommend using matches with a score of 0.8 or above and matched using least two rules. Matching using multiple rules will increase match quality.

To exclude low-confidence matches from your results, use the minimum_match_score parameter.

{
  "minimum_match_score": 0.8
}

Required Rule Groups

Use the required_rule_groups parameter to specify groups of rules. Only results that match one or more of the groups are returned.

{
  "required_rule_groups": [
    ["address", "name"],
    ["address", "phone"]
  ]
}

In this example, a record matches in the following cases:

• The record matches the "address" and "name" rule.
• The record matches the "address" and "phone" rule.
• The record matches the "address", "name", and "phone" rule.

Match Rule Groups Exactly

When match_rule_groups_exactly is true, groups of rules specified in required_rule_groups must match exactly in order to be returned.

{
  "required_rule_groups": [
    ["address", "name"],
    ["address", "phone"]
  ],
  "match_rule_groups_exactly": true
}

In this example, a record matches in the following cases:

• The record matches the "address" and "name" rule.
• The record matches the "address" and "phone" rule.

The rule set '["address", "name", "phone"]' will not match.

Filters

The filter parameter reduces results to records matching a specified criteria, using the Filter DSL.

Fields

By default, all fields in the Data Dictionary are included in the output. Use the fields parameter to reduce the number of elements returned:

{
  "fields": ["name", "street", "city", "state", "postal_code"]
}

Some contact information, including email addresses, will be used for matching, but will not be included with the matched record. Some data may be suppressed for certain records and will not be returned.

Include Labels

The fields returned within records frequently contain encoded values that reference lookup data. To retrieve the labels for lookups, add the include_labels option:

{
  "include_labels": true
}

Read the Lookups API documentation for more information.

Limit

By default, one match is returned. Specify a limit parameter to retrieve multiple matches. When limit is specified, an array of documents is returned.

{
  "identifiers": {
    "name": "Best Business Ever",
    "street": "Main St",
    "city": "Seattle",
    "state": "WA"
  },
  "limit": 3
}

{
  "documents": [
    {
      "infogroup_id": "243185311",
      "rules": [
        "name",
        "address"
      ],
      "score": 0.85,
      "attributes": {
        "city": "Seattle",
        "name": "Best Business Ever",
        "state": "WA",
        "street": "1544 Main St"
      }
    },
    {
      "infogroup_id": "243185311",
      "rules": [
        "name",
        "address"
      ],
      "score": 0.82,
      "attributes": {
        "city": "Seattle",
        "name": "Best Business Forever",
        "state": "WA",
        "street": "15 Main Street"
      }
    },
    {
      "infogroup_id": "243185311",
      "rules": [
        "name",
        "address"
      ],
      "score": 0.80,
      "attributes": {
        "city": "Seattle",
        "name": "Best Business Forever-Forever",
        "state": "WA",
        "street": "544 Main St"
      }
    }
  ]
}

Packages

Select packages of fields by providing a package param_key to the packages parameter. By default, every field on a package is returned. The packages parameter is combined with the fields parameter to return only specified fields.

{
  "packages": ["base_v1", "contacts_v1"]
}

Bulk Match

Use bulk requests to process large volumes of match requests in a batch:

• Create a batch
• Add match requests
• Retrieve results

Create a Batch

POST /v1/places/match/batch

Start by creating a batch. The initial request can include up to 1,000 match requests:

curl -XPOST https://qa.api.data-axle.com/v1/places/match/batch -d '{
  "identifiers": [
    {
      "reference_id": "123",
      "name": "Best Business Ever",
      "street": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98103"
    },
    {
      "reference_id": "124",
      "name": "Best Coffee Ever",
      "street": "456 Central Way",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98103"
    }
  ]
}

The immediate response includes a batch_id and an array of objects containing a match_id. Each match_id is returned in the order the match request identifiers were submitted:

{
  "batch_id": "8a140451fe3f095f1c205cf185efffec",
  "matches": [
    {
      "match_id": "5cbb3b15c8bee0f706239b45cb763fed"
    },
    {
      "match_id": "2e849855d32e1e20eb33e3b74a7785b2"
    },
    {
      "match_id": "5f0b1070c3e4761cabf116bbed2b49c4"
    }
  ]
}

Adding Requests

PUT /v1/places/match/batch/:batch_id

Add match requests to an existing batch_id:

curl -XPUT https://qa.api.data-axle.com/v1/places/match/batch/:batch_id -d '{
  "identifiers": [...]
}

Getting Bulk Match Results

GET /v1/places/match/batch/:batch_id

Use the Match Results API with the batch_id to fetch completed results for the batch. Matches that are pending will not appear in the results.

Use the "status" object to determine batch progress. The batch has completed when processed is the same as requests.

{
  "next_token": "13835315192676945401741312",
  "status": {
    "requests": 500,
    "processed": 223
  },
  "documents": [
    {
      "match_id": "5cbb3b15c8bee0f706239b45cb763fed",
      "reference_id": "123",
      "document": {
        "infogroup_id": "939010853",
        "rules": ["address"],
        "score": 0.90,
        "attributes": {
          "name": "Best Business Ever",
          "street": "123 Main St",
          "city": "Seattle",
          "state": "WA",
          "postal_code": "98103"
        }
      }
    },
    {
      "match_id": "5f0b1070c3e4761cabf116bbed2b49c4",
      "reference_id": "125",
      "document": null
    }
  ]
}

Scrolling Through Match Results

Each request returns up to 1,000 results. To read the next set of results, use the next_token from the previous request and append it to the request URL via the since parameter:

curl https://qa.api.data-axle.com/v1/places/match/batch/:batch_id?since=13835315192676945401741312

Repeat this process until an empty list of documents is returned. Store the final next_token for use in future requests from the same batch:

{
  "next_token": "13835315192676945401741312",
  "status": {
    "requests": 500,
    "processed": 500
  },
  "documents": []
}

Bulk Match Parameters

Bulk Match Result Parameters

Bulk Match Result Response

The match result includes the following fields: