Welcome to the AIM API - Alpha!
The AIM API is in an "alpha stage" to gather customer feedback. While in alpha, the API may change in backwards incompatible ways to accommodate for fixes and additions. Breaking changes will be communicated to the primary API contact at least 5 business days in advance.
TSG reserves the right to determine what constitutes a breaking changes. A definition of "breaking changes" will be made available before formal release.
In order to reduce client coupling, the AIM API provides an API discovery document available at:
The primary attributes of interest is the urls object, which provides static names to full or partial URLs.
The AIM API leverages Firebase Authentication to securely authenticate services and users. To enable API usage, service accounts are created and used to generate a secret Refresh Token that is given to the primary API contact.
These Refresh Tokens do not expire and can be used to retrieve short lived ID Tokens. ID Tokens are used to directly communicate with the AIM API, which will validate the ID Token.
In short, the authentication flow looks like the following:
- Exchange a Refresh Token for an ID Token with Firebase
- Use the ID Token with the AIM API
- Repeat step 1 as the previous ID Token expires
Once acquired, the ID Token must be sent in the Authorization HTTP Header as a Bearer token.
As ID Tokens are short lived, a new one must be fetched before expiration and replaced in requests to the API. ID Tokens are JSON Web Tokens, so any standard JWT libary can be used to decode them and inspect the exp entry for a Unix timestamp after which the token will be rejected by the API. A number of JWT libraries are referenced in the link above.
In order to obtain an ID Token, use the id_token url from the Discovery document, which allows us to exchange our Refresh Token for a fresh ID Token.
Make a POST request with the following payload, injecting the Refresh Token as specified: {"grant_type": "refresh_token", "refresh_token": <API Key>}. Extract the id_token field from the response, which contains the ID Token, which can then be sent to the API.
For example, with curl to make the request and jq to extract the field:
ID_TOKEN_URL="<ID Token Discovery URL>"
API_KEY="<Refresh Token>"
curl -fsSl -XPOST \
-H "Content-Type: application/json" \
-d "{\"grant_type\": \"refresh_token\", \"refresh_token\": \"$API_KEY\"}" \
"$ID_TOKEN_URL" \
| jq -r '.id_token'You now have an ID Token that can be used with the AIM API!
In order to prevent abuse and data leaks, Refresh Tokens must be stored securely. In particular, avoid unneeded sharing of Refresh Tokens or storing them in source files/source control.
If you suspect your Refresh Token has been compromised, contact mailto:AIM@thestrawgroup.com as soon as possible. If abuse is suspected, TSG may disable Refresh Tokens immediately and follow up with the API contact.
The Query API is the primary tool provided by the AIM API. It provides powerful data analysis across multiple dimensions of the AIM dataset.
The Query API is comprised of four (4) primary components:
aggregationattributemetricnormalization
Each component has a discovery endpoint to obtain the available items with full metadata. All query urls are based from the warehouse url in the discovery document:
After acquiring an ID Token, start with a few simple API calls. The calls will use curl for demonstration, but of course, any HTTP client will do. In these examples, BASE_URL is set to . Any query results are for demonstration purposes only and do not represent real values.
# Inspect all attributes. Note the rich metadata describing the data type, filter config and values, among other things. These attributes determine how the data can be filtered and grouped.
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/attribute/"
# Inspect all metrics. Notice that metrics have "availability" metadata describing what attributes and normalizations they support.
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/metric/"
# Let's run a query to pull out volume data:
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=date=2018-01"
# [
# {
# "volume":12864.75939
# }
# ]
# By default, calculations are "Per Merchant", but another normalization can be selected. Let's try some different metrics with "Per Transaction"
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=date=2018-01&normalization=transaction"
# [
# {
# "volume": 73.43840
# }
# ]
# In addition to filtering by a specific month, a range can be provided. Once a date range has been specified, it can be "grouped" so the result set contains the average for each month, instead of the average across the months:
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=2018-01,2018-03&group_by=date"
# [
# {
# "date": "2018-01-01",
# "volume": 28352.73849
# },
# {
# "date": "2018-02-01",
# "volume": 27424.03418
# },
# {
# "date": "2018-03-01",
# "volume": 38738.38481
# }
# ]
# Now, let's see the volume for credit and sig debit:
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=date=2018-01;card=credit,sig_debit&group_by=card"
# [
# {
# "card": "credit",
# "volume": 28327.3061
# },
# {
# "card": "sig_debit",
# "volume": 1924.48568
# }
#]
# How about focused on Omaha, Iowa, Kansas, and Missouri?
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=date=2018-01;card=credit,sig_debit;state=MO,KS,NE,IA&group_by=card"
# [
# {
# "card": "credit",
# "volume": 23394.83581
# },
# {
# "card": "sig_debit",
# "volume": 1483.83589
# }
# ]
# Putting these examples together, one can see metrics per transaction in specific states grouped by card and date.
curl -H "Authorization: Bearer $ID_TOKEN" \
"$BASE_URL/query?metrics=volume&filter=date=2018-01,2018-03;card=credit,sig_debit;state=MO,KS,NE,IA&group_by=date,card&normalization=transaction"
# [
# {
# "card": "credit",
# "date": "2018-01-01",
# "volume": 53.77786
# },
# {
# "card": "sig_debit",
# "date": "2018-01-01",
# "volume": 8.38631
# },
# {
# "card": "credit",
# "date": "2018-02-01",
# "volume": 68.85441
# },
# {
# "card": "sig_debit",
# "date": "2018-02-01",
# "volume": 2.41721
# },
# {
# "card": "credit",
# "date": "2018-03-01",
# "volume": 58.09631
# },
# {
# "card": "sig_debit",
# "date": "2018-03-01",
# "volume": 5.42187
# }
# ]
Abstract aggregation operation.
Aggregations
Periods = 3, Frequency = Month
Periods = 6, Frequency = Month
Periods = 12, Frequency = Month
Periods = 18, Frequency = Month
Attributes provide the ability to filter and slice data.
Attributes
Card is an attribute of central importance in the AIM system.
There are 5 basic card types:
- credit
- signature_debit aka sig_debit
- pin_debit
- opt_blue
And 2 non-basic card types:
- bank_cards (credit + sig_debit)
- other_cards
The metrics coming from raw processor data which are reported on individual card types may be filtered and grouped by card types and are referred to as "card metrics" as opposed to "non-card metrics".
A merchant's ticket tier is based on its average number of transactions (or "tickets") over a rolling 12 month period.
A merchant's volume tier is based on its total volume over a rolling 12 month period.
Geographic region of the transaction.
U.S. State of the transaction
Zip code of the transaction
City of the transaction
Sales model code
Industry Classification Type. Currently this is either MCC or SIC.
Hierarchical grouping of Industries
Industry the merchant belongs to.
A grouping of merchants within an organization.
Date is one of the AIM required attributes. Traditionally date has been by month due to month being the frequency of the aim application, though other aggregation levels are possible and may show up in the future. The term era is used to denote a chunk of time. Ex. The month of June, as opposed to June 1.
Binary on if the merchant is part of a chain or not.
Year merchant entered the market
Base metric class.
Metrics
Processing Cost Contains card components only
Total Cost := Total Cost Card + Total Cost Noncard
Gross Revenue := Gross Revenue Card + Gross Revenue Noncard Contains card and noncard components
Gross Processing Revenue Contains card components only
Net Revenue := Net Revenue Card + Net Revenue Noncard Contains card and noncard components
Net Processing Revenue Contains card components only
Association And Switch Fees Cost No card components
Association Fees Cost
Switch Fees Cost
Interchange Fees Cost No card components
Other Fees Cost No card components
Other Cost No card components
Residuals Cost No card components
Legacy Account Annual Fees Revenue No card components
Legacy Account Monthly Fees Revenue No card components
Discount Revenue Contains card components only
Equipment and Other Revenue Contains card components only
Gross Profit Revenue Contains card components only
Legacy Account Annual and Monthly Fees Revenue Contains card components only
Other Fees Revenue No card components
PCI Annual And Monthly Fees Revenue No card components
Transaction Fees Revenue No card components
Transaction Contains card components only
Volume Contains card components only
Abstract Metric Normalizer.
AIM normalizations are of the form: sum(metric)/sum(normalizing_metric) .
There are three columns used in AIM normalization (with corresponding units):
- Volume ($)
- Transactions (-)
- Active Merchants (-)
Where "-" is a null unit.
Unit Matrix::
=================== ====== ============ ================
Metric / Normalizer Volume Transactions Active Merchants
=================== ====== ============ ================
Transactions - - -
Volume - $ $
All Other Metrics - $ $
=================== ====== ============ ================
Normalizations
Active Merchants In order to be considered active a merchant has to have non-zero Volume and Net Revenue > 0. Unitless due to being a count.
Transactions - Unitless due to being a count.
Volume - Units in dollars.
© The Strawhecker Group. All Rights Reserved.
<script src="./README.js"></script>