TargetSmart¶
Overview¶
TargetSmart provides access to voter and consumer data for the progressive community. Currently, there are two TargetSmart services that are supported by two Parsons classes, each requiring separate credentials:
TargetSmartAPI
: Single record lookup with HTTPS. This class provides methods to support searching for individual people, voters, and district information for a geographic location.TargetSmartAutomation
: Bulk record matching with SFTP. This class provides general methods for processing files instead of individual records.
Note
- Authentication
Log in to My TargetSmart to access authentication credentials. You will need an API key to use the
TargetSmartAPI
class, and an SFTP username and password to use theTargetSmartAutomation
class.For more information, see the API documentation.
TargetSmart¶
Quickstart¶
To instantiate TargetSmartAPI
, you can either store your API Key as the environmental variable
TS_API_KEY
, or pass it in as an argument:
from parsons import TargetSmartAPI
# First approach: Store API key as an environmental variable
ts_api = TargetSmartAPI()
# Second approach: Pass API key as an argument
ts_api = TargetSmartAPI(api_key='my_api_key')
You can then call various endpoints:
# Search for a person record using an email address
ts_api.data_enhance(search_id='test@email.com', search_id_type='email')
# Search for district information using an address
ts_api.district(search_type='address', address='123 test st, Durham NC 27708')
API¶
-
class
parsons.
TargetSmartAPI
(api_key=None)[source]¶ -
data_enhance
(search_id, search_id_type='voterbase', state=None)¶ Searches for a record based on an id or phone or email address
- Args:
- search_id: str
- The primary key or email address or phone number
- search_id_type: str
- One of
voterbase
,exacttrack
,abilitec_consumer_link
,phone
,email
,smartvan
,votebuilder
,voter
,household
. - state: str
- Two character state code. Required if
search_id_type
ofsmartvan
,votebuilder
orvoter
.
- Returns
- Parsons Table
- See Parsons Table for output options.
-
district
(search_type='zip', address=None, zip5=None, zip4=None, state=None, latitude=None, longitude=None)¶ Return district information based on a geographic point. The method allows you to search based on the following:
Search Type Search Type Name Required kwarg(s) Zip Code zip
zip5
,zip4
Address address
address
Point point latitude
,longitude
- Args:
- search_type: str
- The type of district search to perform. One of
zip
,address
orpoint
. - address: str
- An uparsed full address
- zip5: str
- The USPS Zip5 code
- zip4: str
- The USPS Zip4 code
- state: str
- The two character state code
- latitude: float or str
- Valid latitude floating point
- lontitude: float or str
- Valid longitude floating point
- Returns:
- Parsons Table
- See Parsons Table for output options.
-
phone
(table)¶ Match based on a list of 500 phones numbers. Table can contain up to 500 phone numbers to match
- Args:
- table: parsons table
- See Parsons Table. One row per phone number, up to 500 phone numbers.
- Returns:
- See Parsons Table for output options.
-
radius_search
(first_name, last_name, middle_name=None, name_suffix=None, latitude=None, longitude=None, address=None, radius_size=10, radius_unit='miles', max_results=10, gender='a', age_min=None, age_max=None, composite_score_min=1, composite_score_max=100, last_name_exact=True, last_name_is_prefix=False, last_name_prefix_length=10)¶ Search for a person based on a specified radius
- Args:
- first_name: str
- One or more alpha characters
- last_name: str
- One or more alpha characters
- middle_name: str
- One or more alpha characters
- name_suffix: str
- One or more alpha characters
- latitude: float
- Floating point number (e.g. 33.738987255507)
- longitude: float
- Floating point number (e.g. -116.40833849559)
- address: str
- Any geocode-able address
- address_type: str
reg
for registration (default) ortsmart
for TargetSmart- radius_unit: str
- One of
meters
,feet
,miles
(default), orkilometers
. - max_results: int
- Default of
10
. An integer in range [0 - 100] - gender: str
- Default of
a
. One ofm
,f
,u
,a
. - age_min: int
- A positive integer
- age_max: int
- A positive integer
- composite_score_min: int
- An integer in range [1 - 100]. Filter out results with composite score less than this value.
- composite_score_max: int
- An integer in range [1 - 100]. Filter out results with composite score greater than this value.
- last_name_exact: boolean
- 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
orlast_name_prefix_length
. - last_name_is_prefix: boolean
- 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 iflast_name_exact
is enabled. - last_name_prefix_length: int
- 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.
- Returns
- Parsons Table
- See Parsons Table for output options.
-
voter_registration_check
(first_name=None, last_name=None, state=None, street_number=None, street_name=None, city=None, zip_code=None, age=None, dob=None, phone=None, email=None, unparsed_full_address=None)¶ Searches for a registered individual, returns matches.
A search must include the at minimum first name, last name and state.
- Args:
- first_name: str
- Required; One or more alpha characters. Trailing wildcard allowed
- last_name: str
- Required; One or more alpha characters. Trailing wildcard allowed
- state: str
- Required; Two character state code (e.g.
NY
) - street_number: str
- Optional; One or more alpha characters. Trailing wildcard allowed
- street_name: str
- Optional; One or more alpha characters. Trailing wildcard allowed
- city: str
- Optional; The person’s home city
- zip_code: str
- Optional; Numeric characters. Trailing wildcard allowed
- age; int
- Optional; One or more integers. Trailing wildcard allowed
- dob; str
- Numeric characters in YYYYMMDD format. Trailing wildcard allowed
- phone; str
- Integer followed by 0 or more * or integers
- email: str
- Alphanumeric character followed by 0 or more * or legal characters (alphanumeric, @, -, .)
- unparsed_full_address: str
- One or more alphanumeric characters. No wildcards.
- Returns
- Parsons Table
- See Parsons Table for output options.
-
:inherited-members:
Automation¶
Quickstart¶
To instantiate TargetSmartAutomation
, you can either store your SFTP username and password
as the environmental variables TS_SFTP_USERNAME
and TS_SFTP_PASSWORD
, or pass them in as
keyword arguments:
from parsons import TargetSmartAutomation
# First approach: Store SFTP username and password as environmental variables
ts_auto = TargetSmartAutomation()
# Second approach: Pass SFTP username and password as arguments
ts_auto = TargetSmartAutomation(username='my_sftp_username', password='my_sftp_password')
You can then call various endpoints:
# Check the status of a match job
ts_auto.match_status(job_name='my_job_name')
# Remove all files for the match job
ts_auto.remove_files(job_name='my_job_name')
API¶
-
class
parsons.
TargetSmartAutomation
(sftp_username=None, sftp_password=None)[source]¶ -
match
(table, job_type, job_name=None, emails=None, call_back=None, remove_files=True)[source]¶ Match a table to TargetSmart using their bulk matching service.
Warning
- Table Columns
- The automation job does not validates the file by column indexes rather than columns names. So, if it expected 10 columns and you only provide 9, it will fail. However, if you provide 10 columns that are out of order, the job will succeed, but the records will not match.
- Args:
- table: Parsons Table Object
- A table object with the required columns. (Required columns provided be TargetSmart)
- job_type: str
- The match job type. This is case sensitive. (Match job names provided by TargetSmart)
- job_name: str
- Optional job name.
- emails: list
- A list of emails that will received status notifications. This is useful in debugging failed jobs.
- call_back: str
- A callback url to which the status will be posted. See TargetSmart documentation for more details.
- remove_files: boolean
- Remove the configuration, file to be matched and matched file from the TargetSmart FTP upon completion or failure of match.
-