Interzoid SDK for Typescript, Generative-AI powered data matching, data quality, and data normalization for organization and individual name data
npm install @interzoid/data-matchingVersion: 1.2.7
This is a Node.js SDK for Interzoid's Generative-AI powered data matching, data quality, data cleansing, and data
normalization for organization and individual name data. Functions include the generation of similarity keys (also
called match keys) for identifying and matching inconsistent name data, as well as comparing and scoring data for
matching purposes.
The concept is that the same similarity key will be algorithmically generated for different permutations of the same
data content, such as GE, Gen Elec, General Electric all generating the same similarity key. Then, these similarity keys
can be used as the basis of matching data, identifying duplicates, and resolving inconsistencies that can otherwise
degrade the usefulness and value of data-driven applications, processes, or anything else that makes use of data. These
similarity keys form the basis of many of the different functions available in the SDK that make use of Generative AI,
Machine Learning, specialized algorithms, and extensive knowledge bases - all in the Cloud - to provide its results.
These include functions that generate similarity keys for custom use, functions that score matches for certain use
cases, and functions that process and perform matching functions with entire database tables and datasets.
#### Table of Contents
1. API Key
2. Installation
3. Data Matching APIs
1. Match Key Functions
1. Full Name Match Key
2. Company Name Match Key
3. Address Match Key
2. Match Score Functions
1. Full Name Match Score
2. Organization Name Match Score
4. Interzoid Cloud Data Connect
1. Introduction
2. Matching Process
3. Sources
4. Processing Categories
5. Connection Strings
6. Match and write keys to a new cloud database table
7. Match Key Report for a cloud database table
8. Text File Match Key Report
5. Interzoid Account Information (Remaining Credits)
---
Please visit https://www.interzoid.com/register-api-account to register for an API key and receive free usage credits.
This API key will be used as a parameter with each call to the API (via the SDK function) for authentication and usage
tracking.
---
The Interzoid SDK requires Node.js v14 or greater.
``shell`
npm install @interzoid/data-matching
---
Interzoid uses algorithmically generated similarity keys leveraging Generative AI, Large Language Models (LLMs), Machine
Learning, specialized algorithms, and extensive knowledge bases to intelligently match data within or across data
sources. Match rates can increase significantly when similarity keys are used with important data.
To learn more about the technology behind these APIs and to better understand how to make use of similarity keys, please
visit https://docs.interzoid.com/entries/understanding-data-matching
#### Full Name Match Key
This API provides a hashed similarity key from the input data used to match with other similar full name data. Use the
generated similarity key, rather than the actual data itself, to match and/or sort individual name data by similarity as
similar individual names will generate the same similarity key. This avoids the problems of data inconsistency,
misspellings, and name variations when matching within a single dataset, and can also help matching across datasets or
for more advanced searching.
##### Example
`typescript
import { getFullNameMatchKey } from '@interzoid/data-matching';
async function fullNameMatch() {
const result = await getFullNameMatchKey({ apiKey: 'your-interzoid-api-key', fullName: 'John Smith' });
console.log(result);
}
`
##### Result
`json`
{
"simKey": "N1Ai4RfV0SRJf2dJwDO0Cvzh4xCgQG",
"code": "Success",
"credits": "9999"
}
##### Additional documentation
https://interzoid.com/apis/individual-name-matching
---
#### Company Name Match Key
This API provides a hashed similarity key from the input data used to match with other similar company name data. Use
the generated similarity key, rather than the actual data itself, to match and/or sort company name data to identify
inconsistently represented company and organization name data, as similar organization and company names will generate
the same similarity key. This avoids the problems of data inconsistency, misspellings, and name variations when matching
within a single dataset or across multiple data sources.
The optional algorithm parameter provides multiple matching algorithms:
| Algorithm | Description |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| wide | Very fast algorithm with a wider umbrella of similarity. Better when you have other data that will also serve as part of match criteria. |narrow
| | Very fast algorithm, more stringent than wide. Better if you are matching on company or organization name only. |ai-medium-wide
| | (Recommended) High matching accuracy with a wider similarity range, especially for use with the availability of additional matching criteria. Recommended for most use cases, but may have longer response times. |ai-medium-narrow
| | Best matching accuracy when matching solely on company or organization names without any other match criteria. Provides the most precise matching, but may have longer response times. |ai-plus-wide
| | Balances speed and precision with a wider similarity umbrella. Ideal for matching with additional data criteria. |ai-plus-narrow
| | Balances speed and precision with a more stringent matching criteria. Better for matching solely on company or organization names. |
The default algorithm is ai-medium-wide.
##### Example
`typescript
import { getCompanyNameMatchKey } from '@interzoid/data-matching';
async function companyNameMatch() {
const result = await getCompanyNameMatchKey({
apiKey: 'your-interzoid-api-key',
company: 'Microsoft',
algorithm: 'ai-medium-wide'
});
console.log(result);
}
`
##### Result
`json`
{
"simKey": "cZdRqd6Ya6FBDPmFpn4_USiTu2DVoYO32ANw1Z5NYN0",
"code": "Success",
"credits": "9999"
}
##### Additional documentation
https://interzoid.com/apis/company-name-matching
---
#### Address Match Key
This API provides a hashed similarity key from the input data used to match with other similar address data. Use the
generated similarity key, rather than the actual data itself, to match and/or sort address data by similarity, as
similar addresses will generate the same similarity key. This avoids the problems of data inconsistency, misspellings,
and address element variations when matching either withing a single dataset, or across datasets. It also provides for
broader searching capabilities.
You can choose from following matching algorithms:
| Algorithm | Description |
|--------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| narrow | Matches considering unit designators (suite, apt, etc.). Very fast but less accurate than AI options. |wide
| | Matches on street address only, ignoring unit designators. Very fast but less accurate than AI options. |ai-medium-narrow
| | (Recommended) Best accuracy, considering unit designators. Recommended algorithm, but API response can take a little bit longer. |ai-medium-wide
| | Best accuracy, matching on street address only. API can take a little longer but provides high-quality results. |ai-plus-narrow
| | AI-enhanced matching considering unit designators. Second-best in performance and accuracy. |ai-plus-wide
| | AI-enhanced matching on street address only. Second-best in performance and accuracy. |
##### Example
`typescript
import { getAddressMatchKey } from '@interzoid/data-matching';
async function addressMatch() {
const result = await getAddressMatchKey({
apiKey: 'your-interzoid-api-key',
address: '500 main street',
algorithm: 'ai-medium-narrow'
});
console.log(result);
}
`
##### Result
`json`
{
"simKey": "T8O0ROaEgJIFhqcgg7SyCBjRryRVa43oMO2sMlq9r0s",
"code": "Success",
"credits": "9999"
}
##### Additional documentation
https://interzoid.com/apis/street-address-matching
---
We provide two operations for match scoring: Organization name and Full name. The request parameters for these
operations are identical--provide two values and the API returns a matching score on a scale of 0-100 indicating how
similar the two values are and how close they are to potentially being a match. This score is determined through a
series of logic that includes the use of Generative AI, Machine Learning, specialized algorithms, and extensive
knowledge bases. Best practices include setting a threshold, for example 50, 60, or 70 as indicating a potential match
and then dealing with the potential matches as desired.
#### Full Name Match Score
This API provides a match score (likelihood of matching) between two individual names on a scale of 0-100, where 100 is
the highest possible match.
`typescript
import { getFullNameMatchScore } from '@interzoid/data-matching';
async function fullNameMatchScore() {
const result = await getFullNameMatchScore({
apiKey: 'your-interzoid-api-key',
value1: 'John Smith',
value2: 'John Smyth'
});
console.log(result);
}
`
##### Result
`json`
{
"score": "80",
"code": "Success",
"credits": "9999"
}
---
#### Organization Name Match Score
This API provides a match score (likelihood of matching) ranging from 0 to 100 between two organization names.
`typescript
import { getOrganizationMatchScore } from '@interzoid/data-matching';
async function organizationNameMatchScore() {
const result = await getOrganizationNameMatchScore({
apiKey: 'your-interzoid-api-key',
value1: 'Apple',
value2: 'Apple Inc.'
});
console.log(result);
}
`
##### Result
`json`
{
"score": "95",
"code": "Success",
"credits": "9998"
}
---
Interzoid's Cloud Data Connect is a set of functions that allow you to match data in your cloud database or delimited
text file such as CSV and TSV with Interzoid's data matching algorithms.
The process parameter determines the type of matching process to run. The package provides an enum
called that contains the available options.
| Process | Description |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Process.MATCH_REPORT | Generate a report of all found clusters of similar data that share the same generated similarity key. |Process.CREATE_TABLE
| | Creates a new table in the source database with all the similarity keys for each record in the source table, so they can be used for additional queries. |Process.GEN_SQL
| | Generate the SQL INSERT statements to store the similarity keys in a database for ability to review before execution. |Process.KEYS_ONLY
| | Output a generated similarity key for every record in the dataset. |
The source parameter determines the type of data source containing the data you are performing matching functionsenum
with. The package provides an called Source that contains the available options.
Some commonly used examples are:
| Source | Description |
|---------------------|--------------------------------------|
| Source.MYSQL | Match data in a MySQL database. |Source.POSTGRES
| | Match data in a PostgreSQL database. |Source.MARIADB
| | Match data in a MariaDB database. |Source.DATABRICKS
| | Match data in a Databricks table. |Source.CSV
| | Match data in a CSV file. |
Please see the source code for a complete list of available options.
The category parameter determines the type of data you're matching. The package provides an enum
called that contains the available options.
| Category | Description |
|-----------------------|-------------------------|
| Category.COMPANY | Match company names. |Category.INDIVIDUAL
| | Match individual names. |Category.ADDRESS
| | Match addresses. |
The connection parameter is a connection string for your database. The format of the connection string depends on the
database you're connecting to.
Please see this page for examples of connection strings for various
databases.
Set the process parameter to CREATE_TABLE to create a new table in your database with the match keys. The newTable
parameter is the name of the new table to create. This table will be created by the process, and will contain the
original data and the similarity key.
Do not create the table manually; the process will handle the creation.
You'll have to grant the user you're connecting with the ability to create a new table in the database in addition to
the ability to read from the table you're matching.
`typescript
import { getCloudDatabaseMatchKeyReport, Process, Category, Source } from '@interzoid/data-matching';
async function databaseMatchKeyReport() {
const result = await getCloudDatabaseMatchKeyReport({
apiKey: 'your-interzoid-api-key',
process: Process.CREATE_TABLE,
category: Category.COMPANY,
source: Source.MYSQL,
connection: 'db_user:db_password@tcp(db_host)/database',
table: 'companies', // table to match
column: 'companyname', // column to match
reference: 'id', // optional reference column
newTable: 'companies_match_keys' // new table to create
});
console.log(result);
}
`
#### Response
`
"Creating new table...Table companies_match_keys created successfully."
---
#### Response options
* Set json to true to return a JSON object with arrays of match clusters.html
* Set to true to return results in plain text with clusters separated by html tags.
* Don't set either to return results in plain text with clusters separated by newlines.
`typescript
import { getCloudDatabaseMatchKeyReport, Source, Process, Category } from '@interzoid/data-matching';
async function databaseMatchKeyReport() {
const result = await getCloudDatabaseMatchKeyReport({
apiKey: 'your-interzoid-api-key',
process: Process.MATCH_REPORT,
category: Category.COMPANY,
source: Source.MYSQL,
connection: 'db_user:db_password@tcp(db_host)/database',
table: 'companies',
column: 'companyname',
reference: 'id',
json: true,
});
console.log(JSON.stringify(result, null, 2));
}
`
#### Sample Response
`json`
{
"Status": "success",
"Message": "",
"MatchClusters": [
[
{
"Data": "Cisco",
"Reference": "",
"SimKey": "3AmCGk2yvEJ7XUxUmB3dFHxRiVzy4Squ89J-4_lDrxQ"
},
{
"Data": "Cisco Systems",
"Reference": "30",
"SimKey": "3AmCGk2yvEJ7XUxUmB3dFHxRiVzy4Squ89J-4_lDrxQ"
}
],
[
{
"Data": "Netflix",
"Reference": "15",
"SimKey": "8c6BY0KP9MYiDezQaKL3bH3iHfDU2wCMMTD9v0EeZJ8"
},
{
"Data": "\"Netflix, Inc.\"",
"Reference": "34",
"SimKey": "8c6BY0KP9MYiDezQaKL3bH3iHfDU2wCMMTD9v0EeZJ8"
}
]
]
}
---
Provide a URL to a delimited file (CSV or TSV) and the API will return a match key report for the data in the file.
`typescript
import { getDelimitedFileMatchKeyReport, Process, Source, Category } from '@interzoid/data-matching';
async function csvFileMatchReport() {
const result = await getDelimitedFileMatchKeyReport({
apiKey: 'your-interzoid-api-key',
process: Process.MATCH_REPORT,
category: Category.COMPANY,
source: Source.CSV,
table: Source.CSV,
connection: 'https://dl.interzoid.com/csv/companies.csv',
column: '1', // column number to match
json: true,
});
console.log(JSON.stringify(result, null, 2));
}
`
#### Result
`json`
{
"Status": "success",
"Message": "",
"MatchClusters": [
[
{
"Data": "Good Year Tire & Rubber",
"Reference": "",
"SimKey": "140xAiUxvDysV56LZzogzDwLuYLd2U7E5sVAXd1nKd8"
},
{
"Data": "Goodyear Tire Inc",
"Reference": "Transportaions",
"SimKey": "140xAiUxvDysV56LZzogzDwLuYLd2U7E5sVAXd1nKd8"
}
],
[
{
"Data": "Pederson Tooling Inc.",
"Reference": "Transportaions",
"SimKey": "7oOMieCdoyxjt7_oKbE2xGngnZGdG75CFU5pEfhU5z8"
},
{
"Data": "Peterson Tools",
"Reference": "Services",
"SimKey": "7oOMieCdoyxjt7_oKbE2xGngnZGdG75CFU5pEfhU5z8"
}
]
]
}
---
This API retrieves the current amount of remaining purchased (or trial) credits for a license key.
Using this function does not deduct credits from your account.
`typescript
import { getRemainingCredits } from '@interzoid/data-matching';
async function remainingCredits() {
const result = getRemainingCredits({ apiKey: 'your-interzoid-api-key' });
console.log(result);
}
`
#### Result
`json``
{
"credits": "9998",
"code": "Success"
}