ADG API Reference

The Alternative Data Group API is a web service that provides structured company information from unstructured merchant transaction data or domain names reliably.

Our merchant mapper takes text from transactional purchase data and also produces structured company and trading-related information.

The domain mapper converts domain names (URLs) to structured company and trading-related information.

THE BULK API MAPPER IS AVAILABLE ON GITHUB. Click here for the tool Use this tool if you are looking to run multiple inputs through the API.

 

---

Another interesting QUERY for /merchant-mapper would be:

["WALMART.COM 8009666546 BENTONVILLE AR", "TACO BELL 001500153817 CHARLESTON WV", "Purchase #xx255xx WORLDGATE 9 THEATRES HERNDON VA"]

(Notice that’s a JSON list with 3 strings; The entire list can be sent as a single request.)

NOTE: In production, you would sign up in this developer portal to get your own user key.

---

ENDPOINT SUMMARY

The ADG API has three endpoints identified by the HTTP methods they accept, and their paths within the API’s URL:

Method	Path	Purpose
GET	/health	API health check that returns an "OK" message. This is helpful to check that you’re able to authenticate with our web service.
POST	/domain-mapper	Maps domain names from given text to structured company information. More details.
POST	/merchant-mapper	Maps strings from transactional purchase text (e.g. credit card transactions) to structured company information. More details.
POST	/product-mapper	Maps strings from product related text to structured company information. More details.
POST	/pii-ident	Checks whether a given text has personal identifiable information (PII). More details.

Schema

• All API access is over HTTPS.
• The API can be accessed securely at https://api-2445582026130.production.gw.apicast.io/
• All I/O (request or response body data) is in JSON format.

Authentication

The API uses basic HTTP authentication via the X_user_key URL query param. This user key is a token string provided after sign up and log in in this developer portal.
Once you have signed up, and set up your organization, any users you invite can use a shared key, visible API credentials section of the portal, to query our API within the limits of your org’s plan.

For example:

$ curl "https://api-2445582026130.production.gw.apicast.io/health?X_user_key=f816b9125492069f7f2e3b1cc60659f0" Replace f816b9125492069f7f2e3b1cc60659f0 for your own user key.

---

ENDPOINTS

1 – Domain Mapper

Using this endpoint you can map a list of website addresses (containing domain names) to structured company information, such as: company name, financial ticker, related entities, etc.

Endpoint

https://api-2445582026130.production.gw.apicast.io/domain-mapper

Query parameters

• X_user_key: The authentication key you receive when you sign up for the ADG API

Request

POST data

The POST body should contain a JSON array of domain names in the following format: '["google.com", "www.amazon.com", "https://www.walmart.com/account/login", "etc"]'

Limitations

• Up to 1 query strings are accepted per request.
• Each domain name string can be up to 127 characters in length.

Response

Response The response will have a 200 OK status and its body will contain an object with the results for each domain name (queries) in the same order as they were received. These results include as much information about the mapped merchant as possible.

Key	Type	Description
Original Input	string	Input query ran through our process
Company Name	string	The merchant’s most commonly used name; "The Company". Or "No Match / Small Business" if no match was achieved by /merchant-mapper; * "Domain Unreachable" in the case of /domain-mapper
Aliases	string	Other names used to refer to the company
Confidence	float	The confidence score for the main match is a numeric score in the range of 0.0 - 1.55 that our process assigns to the result
Confidence Level	string	Either "low", "medium", or "high". Confidence levels are considered low below 0.41, "medium" at or above 0.41, and "high" at or above 0.75
Alternative Company Matches	string array	Any other company names that are also likely to be correct answers
Related Entities	object array	Any other companies that have a legal relationship with the company in key-value pairs with the following format: Name Related company name Closeness Score The entities are ordered by this value, the higher it is, the more confident we are
Ticker	string	Exchange ticker, if the company is publicly traded
Exchange	string	Primary exchange where the company’s stock is traded, if public
Ticker Company Name	string	Name of the company used in the exchange, if public

Other possible responses

• 401 Unauthorized - Authentication Error: The X_user_key query param contains an invalid value.
• 403 Forbidden - Authentication Missing: The request doesn’t include a X_user_key query param.
• 405 METHOD NOT ALLOWED - This happens when the HTTP method is not POST
• 422 UNPROCESSABLE ENTITY - Validation error: There was a problem with the data submitted in the request. A detailed message of the problem will be included with the response.

Example

Results for domain name aloftnewyorkbrooklyn.com:

 

$ curl -X POST "https://api-2445582026130.production.gw.apicast.io/domain-mapper?X_user_key=f816b9125492069f7f2e3b1cc60659f0" -d'["aloftnewyorkbrooklyn.com"]'

2 – Merchant Mapper

Using this endpoint you can map a list of raw text (e.g. anonymized credit card transactions, online purchasing data, or email receipts) to structured company information, such as: company name, exchange ticker, related entities, etc.

Endpoint

https://api-2445582026130.production.gw.apicast.io/merchant-mapper

Query parameters

• X_user_key: The authentication key you receive when you sign up for the ADG API

Query headers

• X-Input-Type:company name "company name" is a litteral, spelled out. Improves the accuracy if the input data contains only company names, no other miscellaneous text.

Request

POST data

The POST body should contain a JSON array of raw text in the following format:
'["Google playstore purchase", "AMZN MARKETPLACE", "Discounted value brand from Wal*Mart", "etc"]'

Limitations

• Up to 1 query strings are accepted per request.
• Each input string can be up to 127 characters in length.

Response

Given a correctly authenticated and formatted POST request, the response will have a 200 OK status and its body will contain a JSON structure with the results for each input raw text (queries) in the same order as they were received. These results include as much information about the mapped merchant as possible.
Same format and possible responses as Domain Mapper

Example

Results for the transaction text Purchase #xx255xx WORLDGATE 9 THEATRES HERNDON VA :

 

$ curl -X POST "https://api-2445582026130.production.gw.apicast.io/merchant-mapper?X_user_key=f816b9125492069f7f2e3b1cc60659f0" -d'["#xx255xx WORLDGATE 9 THEATRES HERNDON VA"]'

3 – PII Checker

Using this endpoint you can check a list of text to see whether any one contains personal identifiable information (PII). We conform to the Investment Data Standards Organization (IDSO) standards.

Endpoint

https://api-2445582026130.production.gw.apicast.io/pii-ident

Query parameters

• X_user_key: The authentication key you receive when you sign up for the ADG API

Request

POST data

The POST body should contain a JSON array of texts in the following format:
'["Purchase *SQ Uber johndoe@gmail.com San Francisco, CA", "TRANSFER SENT TO +13475887943", "etc"]'
See also the curl statement under the example below.

Limitations

• Up to 1 query strings are accepted per request.
• Each input string can be up to 127 characters in length.

Response

Given a correctly authenticated and formatted POST request, the response will have a 200 OK status and its body will contain a simlpe JSON structure with the result of checking for PII in the given text.
Same possible responses as Domain and Merchant Mapper methods.

Example

Results for the text Purchase *SQ Uber johndoe@gmail.com San Francisco, CA :

 

$ curl -X POST "https://api-2445582026130.production.gw.apicast.io/pii-ident?X_user_key=f816b9125492069f7f2e3b1cc60659f0" -d'["Purchase *SQ Uber johndoe@gmail.com San Francisco, CA"]'

4 – Product Mapper

Using this endpoint you can map a list of raw text relating to product descriptions to structured company information, such as: company name, exchange ticker, related entities, etc.

Endpoint

https://api-2445582026130.production.gw.apicast.io/product-mapper

Query parameters

• X_user_key: The authentication key you receive when you sign up for the ADG API

Request

POST data

The POST body should contain a JSON array of raw text in the following format:
'["Nikon Coolpix", "iPhone 6", "etc"]'

Limitations

• Up to 1 query strings are accepted per request.
• Each input string can be up to 127 characters in length.

Response

Given a correctly authenticated and formatted POST request, the response will have a 200 OK status and its body will contain a JSON structure with the results for each input raw text (queries) in the same order as they were received. These results include as much information about the mapped merchant as possible.
Same format and possible responses as Domain Mapper

Example

Results for the transaction text Purchase iPhone 6

 

$ curl -X POST "https://api-2445582026130.production.gw.apicast.io/product-mapper?X_user_key=f816b9125492069f7f2e3b1cc60659f0" -d'["iPhone 6"]'

---

ACCOUNT PLANS / API RATE LIMITS

You may request a plan upgrade from the Applications page. Contact an ADG representative for more information about plan options and pricing.

---

STATUS CODES

We use the following standard HTTP status code groups:

• 2XX - Success
• 4XX - Error originated in the client side (the user’s request)
• 5XX - Error occurred in the server side (internal to the API)