Default
Residential
For home addresses. Searches the surrounding neighborhood to catch matches text matching misses.
Spatial matching
When customer records differ from the graph on paper, geography reveals the ground truth. The spatial engine evaluates physical distance and neighborhood density to locate individuals who moved locally, live in multi-building communities, or submitted a workplace address.
When the spatial engine runs
Section titled “When the spatial engine runs”The spatial engine runs after deterministic and probabilistic matching, only for records they could not place, and only when you send a first and last name. A spatial match is reported as level S. See how the three approaches fit together →
It is careful by design:
- The name must agree. Being nearby is never enough on its own.
- The search area is sized to the place. Urbanicity, meaning how densely populated the area is, sets how far the engine looks.
- The same confidence bar applies. A spatial match must clear the same minimum confidence as every other match.
Choose a mode
Section titled “Choose a mode”Workplace
Work
For workplace addresses. Searches the wider commuting area for the person’s home.
Mixed lists
Auto
Checks each address. Commercial addresses use the commuting area. Everything else stays residential.
Residential mode
Section titled “Residential mode”Residential mode finds valid customer matches that traditional fuzzy string matching misses.
Traditional fuzzy matching relies on text edit distance. When a customer moves to another building in an apartment community, relocates across town, or crosses a ZIP boundary, their address text looks completely different (“102 Heritage Way” vs. “114 Heritage Way”, or Cambridge vs. Somerville). Traditional fuzzy logic sees conflicting house numbers and street strings and silently drops the record.
The spatial engine bypasses text strings entirely. It places the address in the physical world and evaluates real-world proximity:
- Moves within the same neighborhood or subdivision. Families often move a few streets over to upsize or downsize while staying in the same school district. On paper, both the street number and street name are completely different. On the map, they are a short distance apart in the same residential pocket.
- Multi-building apartment complexes. Many garden apartments, condos, and townhome communities give each building its own street number. A resident who moves from Building A to Building C has a “different” address on paper, but the same community on the map.
- Corner lots and cross-street addressing. Homes on corner lots or subdivided parcels often have driveways or entrances re-assigned to the intersecting street (such as
Main Stvs.Elm Ave). Text matchers see two completely different streets; spatial matching sees the exact same physical property. - Active adult & senior living campuses. Planned retirement communities and continuing care campuses feature separate villas, cottages, and residential drives. When a resident transitions between homes on the same grounds, spatial matching recognizes they remain in the same community.
- Local moves not yet in postal records. People who move across town often show up at the new address before postal change-of-address data reflects it, and some never file a change of address at all.
You sent
- David Chen
- 102 Heritage Way, Apt 3C
- Raleigh, NC 27606
Matched in the graph
- David Chen
- 114 Heritage Way, Apt 1A
- Raleigh, NC 27606
How: The street numbers differ, so text matching cannot connect them. The buildings are a short walk apart in the same community, and the name agrees.
You sent
- Marcus Vance
- 412 Whispering Pines Dr
- Franklin, TN 37064
Matched in the graph
- Marcus Vance
- 805 Oak Hollow Way
- Franklin, TN 37064
How: Both the street number and street name changed when the family moved four streets over. Text matchers cannot connect them, but the spatial engine places both homes 350 meters apart in the same neighborhood.
You sent
- Evelyn Harper
- 104 Main St
- Milford, OH 45150
Matched in the graph
- Evelyn Harper
- 12 Elm Ave
- Milford, OH 45150
How: The property sits on a corner lot where municipal re-addressing or a new driveway shifted the entrance to the intersecting avenue. The person never moved; the engine places both addresses at the exact same physical property.
Work mode
Section titled “Work mode”Work mode is for records where you only know where someone works, such as a whitepaper download, an event registration, or a B2B lead form. The engine searches the realistic commuting area around the workplace for the person with the same name, then resolves to their home profile. You get household and lifestyle enrichment for a contact you only knew professionally.
You sent
- Priya Nair
- 233 S Wacker Dr, Suite 4400
- Chicago, IL 60606
Matched in the graph
- Priya Nair
- 1129 Brookdale Ln
- Naperville, IL 60563
How: The office is a commercial building in a dense downtown. The engine searches the commuting area and finds the same person at home, about 45 km away.
Auto mode
Section titled “Auto mode”Auto mode is for lists that mix home and work addresses, such as CRM exports and event lists. Each address is checked: commercial addresses get the commuting search, and residential addresses keep the neighborhood search. You don’t need to split your list.
If an address can’t be located precisely, auto mode uses the residential search.
Precision controls: name frequency, middle names, and date of birth
Section titled “Precision controls: name frequency, middle names, and date of birth”Physical distance is only part of the solution. To prevent look-alike errors and ensure matches are accurate, the spatial engine calibrates its search radius and confidence scoring using name frequency, middle names, and date of birth:
Rarity scaling
Name frequency
Search distance adapts to name uniqueness. Uncommon names safely permit wider geographic reach, while common names automatically scale down the radius to prevent false positives.
Tie-breakers
Middle names
Middle names and initials provide decisive corroboration. Matching middle names boost candidate confidence, while conflicting middle names penalize or rule candidates out.
Verification
Date of birth
DOB anchors matches in dense areas. Birth year and month agreement confirm individuals with high confidence, while birth dates more than 18 years apart prevent generational mix-ups.
How these signals work together
Section titled “How these signals work together”- Rare vs. common names: A rare name (such as fewer than 25 individuals nationwide in census distribution data) carries high individual signal. The engine safely expands the search radius to capture regional commuters. For common names (such as John Smith), the engine automatically constrains the radius to a tight perimeter unless corroborated by additional signals.
- Middle name corroboration: When multiple individuals in a metropolitan area share the same first and last name, middle names and initials act as powerful tie-breakers. Concordant middle names add confidence, whereas an incompatible middle name or initial significantly penalizes the candidate score.
- Date of birth anchor: Providing a date of birth provides definitive validation. When matching common names, agreement on birth year and month ensures the correct individual is resolved. If date of birth is omitted, the engine remains conservative, requiring closer geographic proximity or distinctive name frequency to clear the confidence floor.
How urbanicity sizes the search
Section titled “How urbanicity sizes the search”A few miles in Manhattan holds far more people than a few miles in rural Montana. The engine classifies each address by urbanicity and sizes the search to match. Tight areas in dense cities prevent look-alike matches, and wider areas in rural places reflect how far people really live and travel.
| Urbanicity | Residential search | Commuting search (work and auto) |
|---|---|---|
| Dense urban | 10 km · 6 mi | 56 km · 35 mi |
| Urban | 20 km · 12 mi | 50 km · 31 mi |
| Suburban | 30 km · 19 mi | 40 km · 25 mi |
| Micropolitan | 40 km · 25 mi | 45 km · 28 mi |
| Small town | 40 km · 25 mi | 45 km · 28 mi |
| Rural | 50 km · 31 mi | 60 km · 37 mi |
Setting the mode
Section titled “Setting the mode”Residential is the default. To change it, set spatial_mode to residential, work, or auto:
- Real time: add
spatial_modenext torecordsin the request body. Microbatch guide → - Files: set
spatial_modewhen you create the file match. The mode applies to the whole file. File match guide →