The searchByAttributes API provides interactive and real time searching of entity attributes within the entity repository, recalling entities matching the search request. searchByAttributes uses the same entity resolution processing utilized when ingesting data to provide non-exact and fuzzy matching capabilities.
The response message from searchByAttributes can contain zero or greater entities matching the requested criteria; detailing the entities that matched the request.
Note: searchByAttributes only searches mapped entity attribute terms and is not a free form search capability. See also Guidelines for Successful Entity Searching.
Similar to many Senzing APIs you may be familiar with, searchByAttributes returns a JSON response message. When interpreting JSON response messages, you'll find it beneficial to pretty print them. One method of achieving this is with the Linux jq command outlined in Interpreting Entity API Response Messages.
Here is an example of using G2Command to call searchByAttributes and the corresponding response message.
This output is from the sample data supplied with a default Senzing API deployment. If you'd like to follow along and test for yourself this data can be loaded with:
cd /opt/senzing/g2/pythonpython G2Loader.py -P
NOTE: These commands assume the default Senzing deployment path and that you don't mind losing any previously loaded data you may have. The -P argument will purge your current Senzing repository of all data! If you are still using the embedded SQLite repository take a look at Backup & Restore SQLite Repository for saving any existing data.
Search Example - Betty Jones
Using G2Command the following can be issued with the sample data loaded:
searchByAttributes '{"NAME_FULL":"Betty Jones", "PASSPORT_NUMBER":"PP22222"}'
After pretty printing the response message the JSON will look similar to:
{
"SEARCH_RESPONSE": {
"RESOLVED_ENTITIES": [
{ <--- Matched entity
"LENS_ID": 1,
"ENTITY_ID": 4,
"MATCH_LEVEL": 2,
"MATCH_KEY": "+NAME+PASSPORT",
"MATCH_SCORE": "13",
"ERRULE_CODE": "CNAME_CF1",
"REF_SCORE": 4,
"FEATURES": {
"ADDRESS": [
{
"FEAT_DESC": "111 FIRST ST LAS VEGAS NV 89111",
"LIB_FEAT_ID": 4,
"UTYPE_CODE": "HOME",
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "111 FIRST ST LAS VEGAS NV 89111",
"LIB_FEAT_ID": 4
}
]
}
],
"DOB": [
{
"FEAT_DESC": "1982-02-02",
"LIB_FEAT_ID": 38,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "1982-02-02",
"LIB_FEAT_ID": 38
}
]
}
],
"DRLIC": [
{
"FEAT_DESC": "DL22222 NV",
"LIB_FEAT_ID": 42,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "DL22222 NV",
"LIB_FEAT_ID": 42
}
]
}
],
"EMAIL": [
{
"FEAT_DESC": "BETH@JONESFAMILY.COM",
"LIB_FEAT_ID": 44,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "BETH@JONESFAMILY.COM",
"LIB_FEAT_ID": 44
}
]
}
],
"GENDER": [
{
"FEAT_DESC": "F",
"LIB_FEAT_ID": 39,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "F",
"LIB_FEAT_ID": 39
}
]
}
],
"NAME": [
{
"FEAT_DESC": "ELIZABETH R JONES",
"LIB_FEAT_ID": 37,
"UTYPE_CODE": "PRIMARY",
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "ELIZABETH R JONES",
"LIB_FEAT_ID": 37
}
]
}
],
"PASSPORT": [
{
"FEAT_DESC": "PP22222 US",
"LIB_FEAT_ID": 43,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "PP22222 US",
"LIB_FEAT_ID": 43
}
]
}
],
"PHONE": [
{
"FEAT_DESC": "702-333-3333",
"LIB_FEAT_ID": 40,
"UTYPE_CODE": "CELL",
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "702-333-3333",
"LIB_FEAT_ID": 40
}
]
}
],
"SSN": [
{
"FEAT_DESC": "322-22-2222",
"LIB_FEAT_ID": 41,
"FEAT_DESC_VALUES": [
{
"FEAT_DESC": "322-22-2222",
"LIB_FEAT_ID": 41
}
]
}
]
},
"MATCH_SCORES": {
"NAME": [
{
"INBOUND_FEAT": "BETTY JONES",
"CANDIDATE_FEAT": "ELIZABETH R JONES",
"GNR_FN": 89,
"GNR_SN": -1,
"GNR_GN": -1,
"GENERATION_MATCH": -1,
"GNR_ON": -1
}
],
"PASSPORT": [
{
"INBOUND_FEAT": "PP22222",
"CANDIDATE_FEAT": "PP22222 US",
"FULL_SCORE": 95
}
]
},
"RECORDS": [
{ <--- Data source record
"JSON_DATA": {
"CELL_PHONE_NUMBER": "702-333-3333",
"DATA_SOURCE": "PEOPLE",
"DATE_OF_BIRTH": "2/2/1982",
"DRIVERS_LICENSE_NUMBER": "DL22222",
"DRIVERS_LICENSE_STATE": "NV",
"DSRC_ACTION": "A",
"EMAIL_ADDRESS": "beth@jonesfamily.com",
"ENTITY_TYPE": "PEOPLE",
"GENDER": "F",
"HOME_ADDR_CITY": "Las Vegas",
"HOME_ADDR_COUNTRY": "US",
"HOME_ADDR_LINE1": "111 First St",
"HOME_ADDR_LINE2": "",
"HOME_ADDR_LINE3": "",
"HOME_ADDR_POSTAL_CODE": "89111",
"HOME_ADDR_STATE": "NV",
"LOAD_ID": "sample_person.csv",
"MAIL_ADDR_CITY": "",
"MAIL_ADDR_COUNTRY": "",
"MAIL_ADDR_LINE1": "",
"MAIL_ADDR_LINE2": "",
"MAIL_ADDR_LINE3": "",
"MAIL_ADDR_POSTAL_CODE": "",
"MAIL_ADDR_STATE": "",
"NIN_COUNTRY": "",
"NIN_NUMBER": "",
"PASSPORT_COUNTRY": "US",
"PASSPORT_NUMBER": "PP22222",
"PRIMARY_NAME_FIRST": "Elizabeth",
"PRIMARY_NAME_LAST": "Jones",
"PRIMARY_NAME_MIDDLE": "R",
"PRIMARY_NAME_PREFIX": "Ms",
"PRIMARY_NAME_SUFFIX": "",
"RECORD_ID": "1004",
"SOCIAL_HANDLE": "",
"SOCIAL_NETWORK": "",
"SSN_NUMBER": "322-22-2222",
"WORK_PHONE_NUMBER": "",
"ENTITY_KEY": "698E526AB9D3F7371875389BCDF3726D0F0A4005",
"ENTITY_NAME": "Ms Elizabeth R Jones",
"MATCH_KEY": "",
"MATCH_SCORE": "",
"ERRULE_CODE": "",
"REF_SCORE": 0,
"MATCH_LEVEL": 0
},
"NAME_DATA": [
"PRIMARY: Jones Elizabeth R Ms"
],
"ATTRIBUTE_DATA": [
"DOB: 2/2/1982",
"GENDER: F"
],
"IDENTIFIER_DATA": [
"DRLIC: DL22222 NV",
"EMAIL: beth@jonesfamily.com",
"PASSPORT: PP22222 US",
"SSN: 322-22-2222"
],
"ADDRESS_DATA": [
"HOME: 111 First St Las Vegas NV 89111 US"
],
"PHONE_DATA": [
"CELL: 702-333-3333"
],
"RELATIONSHIP_DATA": [],
"ENTITY_DATA": [],
"OTHER_DATA": []
} <--- Data source record
]
} <--- Matched entity
]
}
}
searchByAttributes response messages instances contain:
- SEARCH_RESPONSE - Object containing the response from the searchByAttributes API call
- RESOLVED_ENTITIES - Array consisting of zero or greater objects detailing any entities matching the search criteria
Each object within RESOLVED_ENTITIES details and describes a single entity:
- LENS_ID - Reserved for future use
- ENTITY_ID - Unique entity ID assigned to a single entity that met the search criteria
- MATCH_LEVEL - Matches (1), Possible Matches (2), Discovered Relationship (3)
- MATCH_KEY - Details entity features that contributed to meeting the search request
- MATCH_SCORE - Internally assigned score based on matching attributes, can be used for grouping and sorting results
- ERRULE_CODE - The entity resolution rule that fired to satisfy the search request
- REF_SCORE - Arbitrary internally assigned score from 10 to 1 indicating strength of rule, can be used for grouping and sorting results
- FEATURES - Array for each feature comprising the entity involved in the search result and the details for the features
- MATCH_SCORES - For each feature in the search request call, scoring details for the matching entity features
- RECORDS - Array of data source record(s) that comprise the entity identified by the ENTITY_ID
Each object within the RECORDS array details and describes a single data source record that has resolved into the single entity identified by the ENTITY_ID.
- JSON_DATA - The raw data source record attributes sent to Senzing, plus some additional matching attributes added when this record has merged to this single entity
- NAME_DATA - Array containing the name data features for this data source record
- ATTRIBUTE_DATA - Array containing the attribute features for this data source record
- IDENTIFIER_DATA - Array containing the identifier features for this data source record
- ADDRESS_DATA - Array containing the address features for this data source record
- PHONE_DATA - Array containing the phone features for this data source record
- RELATIONSHIP_DATA - Array containing the disclosed relationship features for this data source record
- ENTITY_DATA - Legacy, no longer used
- OTHER_DATA - Array containing the other data attributes that were unmapped to Senzing terms and were not used during the entity resolution process for this data source record
Considering the search response message above, the following observations can be made:
- searchByAttributes returned a single matching entity, identified as ENTITY_ID = 4
- The matching features for the search were NAME and PASSPORT - MATCH_KEY
- The principal (rule) that fired resulting in the entity being returned for the search request was CNAME_CF1 (Close Name and Close F1) - ERRULE_CODE
- The search request name - Betty Jones - matched a candidate entity name - Elizabeth R Jones - with a score of 89 and a passport with a score of 95 - MATCH_SCORES
- Entity ID 4 - Ms Elizabeth R Jones - has only 1 data source record contributing to the entity at this time - RECORDS
- The original data source record information and data attributes are available for display, reporting, etc - JSON_DATA
- The categorised entity features are grouped and available for display, reporting, etc - NAME_DATA, ATTRIBUTE_DATA, IDENTIFIER_DATA, ADDRESS_DATA, PHONE_DATA, RELATIONSHIP_DATA, OTHER_DATA
Search Example - Robert Jones
Performing a new search for Robert Jones and an address in Las Vegas returns the response message outlined below.
searchByAttributes '{"NAME_FULL": "Robert Jones", "ADDR_FULL":"111 First Street,Las Vegas,Nevada,89111"}'
Note: The FEATURES sections have been collapsed for brevity and read "FEATURES": {...}. instead of showing their completeness. Complete sample JSON is attached to this article.
{
"SEARCH_RESPONSE": {
"RESOLVED_ENTITIES": [
{ <--- First matched entity
"LENS_ID": 1,
"ENTITY_ID": 1,
"MATCH_LEVEL": 1,
"MATCH_KEY": "+NAME+ADDRESS",
"MATCH_SCORE": "12",
"ERRULE_CODE": "CNAME_CFF",
"REF_SCORE": 6,
"FEATURES": {... <--- Collapsed for brevity
},
"MATCH_SCORES": {
"ADDRESS": [
{
"INBOUND_FEAT": "111 FIRST STREET,LAS VEGAS,NEVADA,89111",
"CANDIDATE_FEAT": "111 FIRST ST LAS VEGAS NV 89111",
"FULL_SCORE": 99
},
{
"INBOUND_FEAT": "111 FIRST STREET,LAS VEGAS,NEVADA,89111",
"CANDIDATE_FEAT": "111 1ST ST LAS VEGAS NV 89222",
"FULL_SCORE": 95
},
{
"INBOUND_FEAT": "111 FIRST STREET,LAS VEGAS,NEVADA,89111",
"CANDIDATE_FEAT": "PO BOX 111 LAS VEGAS NV 89111",
"FULL_SCORE": 75
}
],
"NAME": [
{
"INBOUND_FEAT": "ROBERT JONES",
"CANDIDATE_FEAT": "ROBERT M JONES",
"GNR_FN": 95,
"GNR_SN": -1,
"GNR_GN": -1,
"GENERATION_MATCH": -1,
"GNR_ON": -1
},
{
"INBOUND_FEAT": "ROBERT JONES",
"CANDIDATE_FEAT": "BOBBY JONES",
"GNR_FN": 97,
"GNR_SN": -1,
"GNR_GN": -1,
"GENERATION_MATCH": -1,
"GNR_ON": -1
}
]
},
"RECORDS": [
{ <--- First data source record
"JSON_DATA": {
"CELL_PHONE_NUMBER": "702-222-2222",
"DATA_SOURCE": "PEOPLE",
"DATE_OF_BIRTH": "1/2/1981",
"DRIVERS_LICENSE_NUMBER": "DL11111",
"DRIVERS_LICENSE_STATE": "NV",
"DSRC_ACTION": "A",
"EMAIL_ADDRESS": "bob@jonesfamily.com",
"ENTITY_TYPE": "PEOPLE",
"GENDER": "M",
"HOME_ADDR_CITY": "Las Vegas",
"HOME_ADDR_COUNTRY": "US",
"HOME_ADDR_LINE1": "111 First St",
"HOME_ADDR_LINE2": "",
"HOME_ADDR_LINE3": "",
"HOME_ADDR_POSTAL_CODE": "89111",
"HOME_ADDR_STATE": "NV",
"LOAD_ID": "sample_person.csv",
"MAIL_ADDR_CITY": "Las Vegas",
"MAIL_ADDR_COUNTRY": "US",
"MAIL_ADDR_LINE1": "PO Box 111",
"MAIL_ADDR_LINE2": "",
"MAIL_ADDR_LINE3": "",
"MAIL_ADDR_POSTAL_CODE": "89111",
"MAIL_ADDR_STATE": "NV",
"NIN_COUNTRY": "",
"NIN_NUMBER": "",
"PASSPORT_COUNTRY": "US",
"PASSPORT_NUMBER": "PP11111",
"PRIMARY_NAME_FIRST": "Robert",
"PRIMARY_NAME_LAST": "Jones",
"PRIMARY_NAME_MIDDLE": "M",
"PRIMARY_NAME_PREFIX": "Mr",
"PRIMARY_NAME_SUFFIX": "Jr",
"RECORD_ID": "1001",
"SOCIAL_HANDLE": "@bobjones27",
"SOCIAL_NETWORK": "twitter",
"SSN_NUMBER": "311-11-1111",
"WORK_PHONE_NUMBER": "800-201-2001",
"ENTITY_KEY": "385E9EEC1A7C66575F0184A1371D564F2B8BD673",
"ENTITY_NAME": "Mr Robert M Jones Jr",
"MATCH_KEY": "",
"MATCH_SCORE": "",
"ERRULE_CODE": "",
"REF_SCORE": 0,
"MATCH_LEVEL": 0
},
"NAME_DATA": [
"PRIMARY: Jones Robert M Mr Jr"
],
"ATTRIBUTE_DATA": [
"DOB: 1/2/1981",
"GENDER: M"
],
"IDENTIFIER_DATA": [
"DRLIC: DL11111 NV",
"EMAIL: bob@jonesfamily.com",
"LOGIN_ID: twitter @bobjones27",
"PASSPORT: PP11111 US",
"SSN: 311-11-1111"
],
"ADDRESS_DATA": [
"HOME: 111 First St Las Vegas NV 89111 US",
"MAIL: PO Box 111 Las Vegas NV 89111 US"
],
"PHONE_DATA": [
"CELL: 702-222-2222",
"WORK: 800-201-2001"
],
"RELATIONSHIP_DATA": [],
"ENTITY_DATA": [],
"OTHER_DATA": []
}, <--- End of first data source record
{ <--- Second data source record
"JSON_DATA": {
"CELL_PHONE_NUMBER": "",
"DATA_SOURCE": "PEOPLE",
"DATE_OF_BIRTH": "2/1/1981",
"DRIVERS_LICENSE_NUMBER": "",
"DRIVERS_LICENSE_STATE": "",
"DSRC_ACTION": "A",
"EMAIL_ADDRESS": "",
"ENTITY_TYPE": "PEOPLE",
"GENDER": "M",
"HOME_ADDR_CITY": "Las Vegas",
"HOME_ADDR_COUNTRY": "",
"HOME_ADDR_LINE1": "111 1st St",
"HOME_ADDR_LINE2": "",
"HOME_ADDR_LINE3": "",
"HOME_ADDR_POSTAL_CODE": "89222",
"HOME_ADDR_STATE": "NV",
"LOAD_ID": "sample_person.csv",
"MAIL_ADDR_CITY": "",
"MAIL_ADDR_COUNTRY": "",
"MAIL_ADDR_LINE1": "",
"MAIL_ADDR_LINE2": "",
"MAIL_ADDR_LINE3": "",
"MAIL_ADDR_POSTAL_CODE": "",
"MAIL_ADDR_STATE": "",
"NIN_COUNTRY": "",
"NIN_NUMBER": "",
"PASSPORT_COUNTRY": "",
"PASSPORT_NUMBER": "",
"PRIMARY_NAME_FIRST": "Bobby",
"PRIMARY_NAME_LAST": "Jones",
"PRIMARY_NAME_MIDDLE": "",
"PRIMARY_NAME_PREFIX": "",
"PRIMARY_NAME_SUFFIX": "",
"RECORD_ID": "1002",
"SOCIAL_HANDLE": "",
"SOCIAL_NETWORK": "",
"SSN_NUMBER": "",
"WORK_PHONE_NUMBER": "",
"ENTITY_KEY": "FF1C69034FA4B3D82193A42843937478EBA2CB61",
"ENTITY_NAME": "Bobby Jones",
"MATCH_KEY": "+NAME+DOB+GENDER+ADDRESS",
"MATCH_SCORE": "14",
"ERRULE_CODE": "CNAME_CFF_CEXCL",
"REF_SCORE": 8,
"MATCH_LEVEL": 1
},
"NAME_DATA": [
"PRIMARY: Jones Bobby"
],
"ATTRIBUTE_DATA": [
"DOB: 2/1/1981",
"GENDER: M"
],
"IDENTIFIER_DATA": [],
"ADDRESS_DATA": [
"HOME: 111 1st St Las Vegas NV 89222"
],
"PHONE_DATA": [],
"RELATIONSHIP_DATA": [],
"ENTITY_DATA": [],
"OTHER_DATA": []
} <--- End of second data source record
]
}, <--- End of first matched entity
{ <--- Second matched entity
"LENS_ID": 1,
"ENTITY_ID": 4,
"MATCH_LEVEL": 3,
"MATCH_KEY": "+ADDRESS",
"MATCH_SCORE": "2",
"ERRULE_CODE": "CFF",
"REF_SCORE": 2,
"FEATURES": {... <--- Collapsed
},
"MATCH_SCORES": {
"ADDRESS": [
{
"INBOUND_FEAT": "111 FIRST STREET,LAS VEGAS,NEVADA,89111",
"CANDIDATE_FEAT": "111 FIRST ST LAS VEGAS NV 89111",
"FULL_SCORE": 99
}
],
"NAME": [
{
"INBOUND_FEAT": "ROBERT JONES",
"CANDIDATE_FEAT": "ELIZABETH R JONES",
"GNR_FN": 76,
"GNR_SN": -1,
"GNR_GN": -1,
"GENERATION_MATCH": -1,
"GNR_ON": -1
}
]
},
"RECORDS": [
{ <--- Only data source record
"JSON_DATA": {
"CELL_PHONE_NUMBER": "702-333-3333",
"DATA_SOURCE": "PEOPLE",
"DATE_OF_BIRTH": "2/2/1982",
"DRIVERS_LICENSE_NUMBER": "DL22222",
"DRIVERS_LICENSE_STATE": "NV",
"DSRC_ACTION": "A",
"EMAIL_ADDRESS": "beth@jonesfamily.com",
"ENTITY_TYPE": "PEOPLE",
"GENDER": "F",
"HOME_ADDR_CITY": "Las Vegas",
"HOME_ADDR_COUNTRY": "US",
"HOME_ADDR_LINE1": "111 First St",
"HOME_ADDR_LINE2": "",
"HOME_ADDR_LINE3": "",
"HOME_ADDR_POSTAL_CODE": "89111",
"HOME_ADDR_STATE": "NV",
"LOAD_ID": "sample_person.csv",
"MAIL_ADDR_CITY": "",
"MAIL_ADDR_COUNTRY": "",
"MAIL_ADDR_LINE1": "",
"MAIL_ADDR_LINE2": "",
"MAIL_ADDR_LINE3": "",
"MAIL_ADDR_POSTAL_CODE": "",
"MAIL_ADDR_STATE": "",
"NIN_COUNTRY": "",
"NIN_NUMBER": "",
"PASSPORT_COUNTRY": "US",
"PASSPORT_NUMBER": "PP22222",
"PRIMARY_NAME_FIRST": "Elizabeth",
"PRIMARY_NAME_LAST": "Jones",
"PRIMARY_NAME_MIDDLE": "R",
"PRIMARY_NAME_PREFIX": "Ms",
"PRIMARY_NAME_SUFFIX": "",
"RECORD_ID": "1004",
"SOCIAL_HANDLE": "",
"SOCIAL_NETWORK": "",
"SSN_NUMBER": "322-22-2222",
"WORK_PHONE_NUMBER": "",
"ENTITY_KEY": "698E526AB9D3F7371875389BCDF3726D0F0A4005",
"ENTITY_NAME": "Ms Elizabeth R Jones",
"MATCH_KEY": "",
"MATCH_SCORE": "",
"ERRULE_CODE": "",
"REF_SCORE": 0,
"MATCH_LEVEL": 0
},
"NAME_DATA": [
"PRIMARY: Jones Elizabeth R Ms"
],
"ATTRIBUTE_DATA": [
"DOB: 2/2/1982",
"GENDER: F"
],
"IDENTIFIER_DATA": [
"DRLIC: DL22222 NV",
"EMAIL: beth@jonesfamily.com",
"PASSPORT: PP22222 US",
"SSN: 322-22-2222"
],
"ADDRESS_DATA": [
"HOME: 111 First St Las Vegas NV 89111 US"
],
"PHONE_DATA": [
"CELL: 702-333-3333"
],
"RELATIONSHIP_DATA": [],
"ENTITY_DATA": [],
"OTHER_DATA": []
} <--- End of only data source record
]
} <--- End of second matched entity
]
}
}
Considering this search response message, the following observations can be made:
- searchByAttributes returned 2 matching entities - ENTITY_ID = 1 and ENTITY_ID = 4
- First returned entity - ENTITY_ID = 1
- The matching features for the search were NAME and ADDRESS - MATCH_KEY
- The principal (rule) that fired resulting in the entity being returned for the search request was CNAME_CFF (Close Name and Close Frequency Few) - ERRULE_CODE
- The search request name - Robert Jones - matched 2 candidate entity names, Robert M Jones with a score of 95 and Bobby Jones with a score of 97 - MATCH_SCORES
- The search request address - 111 First Street... - matched 3 candidate entity addresses with scores ranging from 75 to 99 - MATCH_SCORES
- This entity consists of 2 data source records that have merged together, both from the PEOPLE data source (DATA_SOURCE) with the data source keys (RECORD_ID) of 1001 and 1002 - RECORDS
- Second returned entity - ENTITY_ID = 4
- The matching feature for the search was only ADDRESS - MATCH_KEY
- The principal (rule) that fired resulting in the entity being returned for the search request was CFF (Close Frequency Few) - ERRULE_CODE
- The search request address - 111 First Street... - matched 1 candidate entity address with a score of 99 - MATCH_SCORES
- The search request name - Robert Jones - matched 1 candidate entity name, Elizabeth R Jones with a score of 76. MATCH_KEY indicates this did not contribute to the search being satisfied, only ADDRESS is shown here - MATCH_SCORES
- This entity consists of only 1 data source record contributing to the entity at this time - RECORDS
Comments
0 comments
Please sign in to leave a comment.