Interpreting Entity API Response Messages

Once you start incorporating the insights derived from entity resolution into your own applications via the APIs, interpreting the response messages might be a little unwieldy at first! Using the sample data supplied we'll take a look at how to interpret the JSON response messages. 

Load the Sample Data

The following commands assume default deployment location and new data to be inputted (i.e. you don't have useful data you'd like to maintain already loaded). The commands will purge your currently loaded data. Review the Backup & Restore SQLite Repository article if you'd prefer to preserve existing loaded data.

If you've deployed to a location other than the default /opt/senzing/g2 modify any commands to match your deployment path.

• cd /opt/senzing/g2/python
• python G2Loader.py -P -p demo/sample/project.json
  • -P = Purge the G2 repository before loading
  • -p = Project file to load

Once loading is complete you'll see output similar to:

 

Search and Return an Entity

To quickly work with the G2 APIs we will use the G2Command utility. G2Command is a command line interpreter for interfacing with the APIs, although not fully supported we endeavor to keep it up to date and add enhancements.

Start G2Command:

• python G2Command.py
  • Ensure you are in /opt/senzing/g2/python
• Type help 

We can now use the searchByAttributes API to search for a data source record contained within the sample_person.json file loaded above. The screenshot below doesn't show the complete data, the right hand side has been cut off to be visible here.

• searchByAttributes '{"DATE_OF_BIRTH": "1/2/1981", "EMAIL_ADDRESS": "[e-mail]"}'

The searchByAttributes API located an entity matching the attributes for the date of birth and email address supplied. This is the same search response message any application you built would receive issuing the same API call. 

Parsing a Response Message

To make the response message easier to view and interpret you can use a JSON parser or processor that pretty prints JSON. A powerful command like processor is jq, it isn't always installed on Linux by default yet is typically in the distribution repositories and straightforward to install using your distribution package manager. For example:

• sudo apt install jq
• sudo yum install jq

Note: Be careful using online JSON parsers on your sensitive data, you don't want to be sharing it in such a fashion!

To pretty print the response message using jq, copy the entirety of the response message and paste it into a jq command and surround the response message with single quotes.

• jq . <<< 'RESPONSE_MESSAGE_HERE'

jq will pretty print the response message directly to the terminal. Redirect the output to a file or other location to capture it if you choose. 

Example Search Response Message

A sample parsed search response message with comments to explain the contents. Output is from the sample data and search shown above.Click to open in a new window and enlarge. 

Example Get Entity Response Message

From the sample data request to return the entity with ID = 4

• getEntityByEntityID 4

The response message is very similar in format and comprehension to the search request. Click to open in a new window and enlarge. 

Response Message Observations & Notes

• Resolved entities consist of 1 or more data source records
• An entity details the source records it consists of and matching details that caused it to resolve
• The source records for the entity detail the raw data that was ingested - JSON_DATA
• The source records specify the designated data source name - DATA_SOURCE - to identify the originating source system
• When provided and mapped source records provide the unique key from the source of the supplied record - RECORD_ID
• Search requests indicate what matched to satisfy the search request
• When an entity has discovered relationships to other entities, they are listed in the RELATED_ENTITIES section
• An entity may have zero or more discovered relationships
• Related entities are fully detailed in the response message
• If a related entity is made up of more than 1 source record their details and matching information is shown
• Unmapped but ingested data attributes are detailed in the JSON_DATA section and grouped in the OTHER_DATA section for a source record