Service endpoint¶

https://api.targetsmart.com/person/radius-search

Overview¶

This service can be used to search for individuals within a user specified geographic area defined by a radius centered around a latitude/longitude point. The search center point can be defined by either latitude/longitude or a geo-codable address.

This service is sometimes referred to as “proximity matching”.

Input requests require first name, last name, and lat/lng or address to define the search center. Additional optional parameters allow you to tune the size of the search and filter matches.

The searches can be performed against an individual’s registered address or using the TargetSmart maintained address. The registration address is a standardized version of the address taken from voter file sources. The TargetSmart maintained address accounts for movers and takes into account other data quality issues. By default, the registration address data is used.

Request Parameters¶

Each request uses required and allowed keys. The first_name and last_name keys are required. Additionally, each query must include either latitude and longitude, or a geocode-able address. The search region will be centered at this lat/lng or address value. All other allowed keys shown in the following table are optional.

Additional Parameter Details¶

address_type

Determines if you are searching registration addresses or TargetSmart addresses. The TargetSmart address is the most up to date address for a maintained individual. The registration address is the address used when an individual registered to vote. To include unregistered voters in your search results, you should use the TargetSmart address option. To search official voter file addresses for registered voters, you should use the registration address option

radius_size

Determines size of search region. The maximum radius size is 120 miles. Queries may take longer for larger radius sizes.

max_results

By default the service returns up to 10 results. This can be set to up to 100.

gender

Limit results to a specified gender

Acceptible values:

• m - Only allow male gender coded records
• f - Only allow female gender coded records
• u - Only allow unknown gender coded records
• a - Allow any gender

age_min

If age_max is also used, then database records outside of the given range are excluded from results/scoring. The age range is inclusive. To specify an exact age match, use the same value for both ends of the range. Database records without age/dob information are always included in results

age_max

If age_min is also used, then database records outside of the given range are excluded from results/scoring. The age range is inclusive. To specify an exact age match, use the same value for both ends of the range. Database records without age/dob information are always included in results

composite_score_min

Filter out results with composite score less than this value.

composite_score_max

Filter out results with composite score greater than this value.

last_name_exact

By default, the full last name is used for finding matches if the length of the last name is not longer than 10 characters. As an example, “anders” is less likely to match to “anderson” with this enabled. Disable this option if you are using either last_name_is_prefix or last_name_prefix_length.

last_name_is_prefix

By default, the full last name is used for finding matches. Enable this parameter if your search last name is truncated. This can be common for some client applications that for various reasons do not have full last names. Use this parameter along with last_name_prefix_length to configure the length of the last name prefix. This parameter is ignored if last_name_exact is enabled.

last_name_prefix_length

By default, up to the first 10 characters of the search last name are used for finding relative matches. This value must be between 3 and 10. This parameter is ignored if last_name_exact is enabled.

JSON Response¶

Search responses are JSON objects with the following keys:

• output: The search output. See details below.
• output_size: The number of search matches included in the output.
• search_latitude: The latitude used in the search
• search_longitude: The longitude used in the search
• states_updated: Voter file update date information represented as a JSON object where keys are two character U.S. state codes and values are dates the state voter file was last updated. The date format is YYYYMMDD.

Output

The output key references a list of JSON objects. Each nested object represents a search result and has the following keys:

• similarity_score: Integer score value 0-100 (higher scores are better name matches)
• proximity_score: positive integer score. The higher this value, the closer the result was to the search center relative to other results
• composite_score: Weighted score that takes into account name similarity, distance from center and uniqueness (number of candidate records in block)
• uniqueness_score: A positive integer value that indicates the number of total candidate matches (see below for details)
• confidence_indicator: Categorical string based on composite score range, e.g., “Likely Match” (see below for values)
• distance_km: The approximate distance from the search center to the result (in kilometers)
• distance_miles: The approximate distance from the search center to the result (in miles)
• distance_meters: The approximate distance from the search center to the result (in meters)
• distance_feet: The approximate distance from the search center to the result (in feet)
• data_fields: A JSON object mapping field names to data values for each search result, e.g., “vb.voterbase_age”. The fields that are returned are configured on a per-client basis. Consult our support staff for available fields, data dictionary, etc.

Output sort order

Results are returned sorted descending by composite_score and secondarily sorted ascending by distance.

confidence_indicator

This label is provided as a convenience to digest the name and proximity ranking scores. Obviously, if the actual search target isn’t in the database, a returned false positive isn’t really an “Excellent Match”. This label has reduced value for searches that depend on very common names, e.g., “Bill Smith”, or use large radius sizes.

Possible values:

• Excellent Match
• Highly Likely Match
• Likely Match
• Potential Match
• Loose Match
• No Match

uniqueness_score

• 100: one possible match
• 90: two possible matches
• 80: three possible matches
• 75: four possible matches
• 70: less than seven possible matches
• 60: less than ten possible matches
• 50: less than fifteen possible matches
• 40: less than twenty possible matches
• 20: less than twenty-five possible matches
• 10: less than fifty possible matches
• 1: fifty or more possible matches

proximity_score

This value describes the distance of the search result from the search center in terms of the std. deviation of possible matches average distance.

• 100: Closest matches to search center or any match under one mile
• 95:
• 90:
• 75:
• 60:
• 45:
• 30:
• 15: Matches furthest away from search center

Code Examples¶

🔐 Remember to secure your API key

Never expose your API key in plain text or source control accessible by a third party.

#! /usr/bin/env python3

import os
import requests

api_key = os.environ["TS_API_KEY"]

# Lat/Lon search
response = requests.get(
    "https://api.targetsmart.com/person/radius-search",
    params={
        "latitude": 40.2971079,
        "longitude": -83.2112569,
        "radius_size": 10,
        "radius_unit": "miles",
        "first_name": "BOB",
        "last_name": "SMITH",
    },
    headers={"x-api-key": api_key},
)
response.raise_for_status()
print(response.json())


# Address search
response = requests.get(
    "https://api.targetsmart.com/person/radius-search",
    params={
        "address": "1155 15th St NW #750, Washington, DC",
        "radius_size": 5000,
        "radius_unit": "feet",
        "first_name": "BOB",
        "last_name": "SMITH",
    },
    headers={"x-api-key": api_key},
)
response.raise_for_status()
print(response.json())

#! /usr/bin/env node

const fetch = require("node-fetch");

const targetSmartApiKey = process.env.TS_API_KEY;

// Lat/Lon search
fetch(
  "https://api.targetsmart.com/person/radius-search?" +
    new URLSearchParams({
      latitude: 40.2971079,
      longitude: -83.2112569,
      radius_size: 10,
      radius_unit: "miles",
      first_name: "BOB",
      last_name: "SMITH",
    }).toString(),
  {
    method: "GET",
    headers: {
      "x-api-key": targetSmartApiKey,
    },
  }
)
  .then((res) => res.json())
  .then((json) => console.log(json));

// Address search
fetch(
  "https://api.targetsmart.com/person/radius-search?" +
    new URLSearchParams({
      address: "1155 15th St NW #750, Washington, DC",
      radius_size: 5000,
      radius_unit: "feet",
      first_name: "BOB",
      last_name: "SMITH",
    }).toString(),
  {
    method: "GET",
    headers: {
      "x-api-key": targetSmartApiKey,
    },
  }
)
  .then((res) => res.json())
  .then((json) => console.log(json));

#! /usr/bin/env bash

# Lat/Lon search
result=$(curl -XGET \
    -H "x-api-key: $TS_API_KEY" \
    "https://api.targetsmart.com/person/radius-search?latitude=40.2971079&longitude=-83.2112569&radius_size=10&radius_unit=miles&first_name=BOB&last_name=SMITH")
echo $result

# Address search
result=$(curl -XGET \
    -H "x-api-key: $TS_API_KEY" \
    "https://api.targetsmart.com/person/radius-search?address=1155+15th+St+NW+%23750%2C+Washington%2C+DC&radius_size=5000&radius_unit=feet&first_name=BOB&last_name=SMITH")
echo $result