Give equivalent address spellings one key

Two records can point to one mailbox and still fail a string equality check. A CRM might contain 123 Main St Apt 4, while a billing export has 123 Main Street #4.

match-key-address turns both strings into the same value for joins and duplicate detection. Each call costs $0.005 USDC. 

POST https://x402.agentutility.ai/match-key-address
Content-Type: application/json

{
  "address": "123 Main St Apt 4"
}

An x402-capable client handles the HTTP 402 payment challenge with USDC on Base mainnet, then receives the JSON response.

Watch each variant collapse

The request above returns: 

{
  "input": "123 Main St Apt 4",
  "normalized": "123 main street unit 4",
  "match_key": "123-mn-strt-unt-4"
}

Now send the version from the billing export: 

POST https://x402.agentutility.ai/match-key-address
Content-Type: application/json

{
  "address": "123 Main Street #4"
}

Its response has the same normalized form and key: 

{
  "input": "123 Main Street #4",
  "normalized": "123 main street unit 4",
  "match_key": "123-mn-strt-unt-4"
}

input preserves the trimmed value supplied by the caller. The readable normalized value exposes the standardization result, which is handy for logs and review screens.

Save match_key as the join column. Recognized street types expand to a common spelling, so St becomes street and Ave becomes avenue. Directionals receive the same treatment. Unit markers such as Apt, Suite, and # become unit.

The compact key can also collapse street spellings that sound alike. For example, Main and Maine both map to mn. That catches useful variants, but it means key equality is a candidate signal rather than proof that two records describe the same physical mailbox.

The required address must be a nonempty string with at most 300 characters. Missing input returns HTTP 400. Longer input returns HTTP 413.

Bucket first, score uncertain pairs

Call match-key-address once for each source record, then group rows by match_key. This changes an expensive all-against-all comparison into lookups inside much smaller buckets.

Near variants can land in different buckets when a house number or unit suffix changes. Send those pairs to match-score with type: "address". It costs $0.003 USDC per comparison. 

POST https://x402.agentutility.ai/match-score
Content-Type: application/json

{
  "a": "123 Main St Apt 4, Springfield, IL 62704",
  "b": "123 Main Street Apt 4B, Springfield, IL 62704",
  "type": "address"
}
{
  "a": "123 Main St Apt 4, Springfield, IL 62704",
  "b": "123 Main Street Apt 4B, Springfield, IL 62704",
  "type": "address",
  "score": 91,
  "same_key": false,
  "normalized_a": "123 main street unit 4 springfield il 62704",
  "normalized_b": "123 main street unit 4b springfield il 62704"
}

A score of 91 puts this pair near the top of a review queue. But 4 and 4B may be separate mailboxes, so the caller should require exact unit agreement before merging customer or delivery records.

Equal-key pairs already have the strongest bucket signal. Calling match-score for such a pair returns score: 100 with same_key: true.

Give the router a small decision rule

  • Use match-key-address when the task asks for address joins, deduplication, or grouping across formatting changes.
  • Store both normalized and match_key when a human may inspect proposed merges.
  • Call match-score for close records whose keys differ, preferably inside a set already limited by ZIP Code or another source field.
  • Require exact agreement on fields with delivery meaning, especially the building number and unit.

Keying two records costs $0.010 USDC. Scoring one different-key pair brings that comparison to $0.013 USDC.