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.

 

Try the live API now

(No sign up required)

Click on /merchant-mapper below to show the interactive panel.

Scroll the page to the Parameters section.

The X_USER_KEY param should be f816b9125492069f7f2e3b1cc60659f0. (No change needed)

Paste the example text below into the QUERY window, or click on the yellow box underneath “Model Schema” to the right of it.

Make sure that your query is surrounded by [" and "].

Example: ["THE HOME DEPOT 12/29 #000725801 PURCHASE"]

Click the Try it out! button and scroll down to see the results in the Response Body section.

You can click on /merchant-mapper again to hide its interactive panel.

Feel free to try /domain-mapper in the same way.


LIVE WORKING CURL COMMAND EXAMPLE: curl -X POST "https://api-2445582026130.production.gw.apicast.io/merchant-mapper?X_user_key=f816b9125492069f7f2e3b1cc60659f0" -d'["WORLDGATE 9 THEATRES HERNDON VA"]'


 

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 /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"]'
[
  {
    "Original Input": "aloftnewyorkbrooklyn.com",
    "Company Name": "Marriott International",
    "Aliases": [
      "marriott",
      "Marriott Hotels & Resorts"
      "Marriott International Inc"
      "Marriott Internationals, Inc."
    ],
    "Confidence": 1,
    "Confidence Level": "High",
    "Alternative Company Matches": [],
    "Related Entities": [
      {
        "Name": "Residence Inn by Marriott",
        "Closeness Score": 3.55
      },
      {
        "Name": "Courtyard",
        "Closeness Score": 3.3
      },
      {
        "Name": "Starwood",
        "Closeness Score": 3.18
      },
      ...
    ],
    "Ticker": "MAR",
    "Exchange": "NASDAQ"
    "Ticker Company Name": "MARRIOTT INTERNATIONAL"
  }
]

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

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"]'
[
  {
    "Original Input": "Purchase #xx255xx WORLDGATE 9 THEATRES  HERNDON    VA",
    "Company Name": "AMC",
    "Aliases": [
      "AMC Entertainment Holdings Inc",
    ],
    "Confidence": 0.84,
    "Confidence Level": "High",
    "Alternative Company Matches": [],
    "Related Entities": [
      {
        "Name": "AMC Theatres",
        "Closeness Score": 3.55
      },
      {
        "Name": "Carmike Cinemas",
        "Closeness Score": 3.0
      },
      ...
    ],
    "Ticker": "AMC",
    "Exchange": "NYSE"
    "Ticker Company Name": "AMC ENTERTAINMENT HLDS"
  }
]

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"]'
[
  {
    "Original Input": "Purchase *SQ Uber johndoe@gmail.com San Francisco, CA",
    "PII Detected": true
  }
]

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)