Merchant Search Guide
ⓘ Reading Time: 10 mins
Merchant search is released in beta.
Merchant search allows you to query Spade's database for detailed merchant information. Using merchant search, you can discover a merchant's counterparty ID, MCCs, Spade Categories, affiliated merchants, and more. With this information, you can confidently make critical transaction authorization decisions.
Merchant search is not enabled by default. To request access, please contact us at [email protected].
Searching for a merchant
You can use merchant search to retrieve detailed information about a merchant. Let's try sending the following request to the /merchants endpoint.
Note that the old
/merchants/advancedendpoint is now deprecated. All of this endpoint's functionality is now available at/merchants.
import requests
response = requests.get("https://east.sandbox.spade.com/merchants", params={"name": "walmart"}, headers={"X-Api-Key": "<Your API Key Here>"})
results = response.json()
print(results)
And here's the response we get from this query.
{
"counterparties": [
{
"id": "d730906b-f1a8-49f1-9939-f27390170a6d",
"name": "Walmart",
"similarity": 100.0,
"logo": "https://static.v2.spadeapi.com/logos/d730906bf1a849f19939f27390170a6d/light.png",
"website": "walmart.com",
"affiliates": [
{
"id": "63fd64b8-8d35-44b1-8aef-324a8a1b279c",
"name": "Sam's Club",
"logo": "https://static.v2.spadeapi.com/logos/63fd64b88d3544b18aef324a8a1b279c/light.png",
"website": "samsclub.com"
}
],
"alternates": [
{
"id": "6b4e8b7b-d5dd-37cf-afdf-00d05fe314d2",
"similarity": 0.89
},
{
"id": "28f1c5bd-1785-3b78-bc70-0a42fa6c04aa",
"similarity": 0.89
},
{
"id": "1c735755-fa71-38ff-aea0-ea9b19247a87",
"similarity": 0.89
},
{
"id": "41ccc32d-22db-3ccc-8403-a9e169d58a7d",
"similarity": 0.89
},
{
"id": "92102ff2-fe2d-32bb-a59f-215d4b9c1923",
"similarity": 0.89
}
],
"expectedSpadeCategories": [
{
"id": "011-014-000-000",
"name": "Supermarkets and Grocery Stores",
"icon": "https://static.v2.spadeapi.com/categories/4d937d51e9cd44a0bbed1621363158c2/light.png",
"fullCategoryHierarchy": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-014-000-000",
"name": "Supermarkets and Grocery Stores",
"icon": "https://static.v2.spadeapi.com/categories/4d937d51e9cd44a0bbed1621363158c2/light.png"
}
]
},
{
"id": "011-006-000-000",
"name": "Gas Stations",
"icon": "https://static.v2.spadeapi.com/categories/fac7777cc0044a25a175f264252fd762/light.png",
"fullCategoryHierarchy": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-006-000-000",
"name": "Gas Stations",
"icon": "https://static.v2.spadeapi.com/categories/fac7777cc0044a25a175f264252fd762/light.png"
}
]
},
{
"id": "011-016-000-000",
"name": "Warehouses and Wholesale Stores",
"icon": "https://static.v2.spadeapi.com/categories/06e495ee6c06413988e510e0c581b80b/light.png",
"fullCategoryHierarchy": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-016-000-000",
"name": "Warehouses and Wholesale Stores",
"icon": "https://static.v2.spadeapi.com/categories/06e495ee6c06413988e510e0c581b80b/light.png"
}
]
},
{
"id": "011-018-003-000",
"name": "Discount Stores",
"icon": "https://static.v2.spadeapi.com/categories/3fa31bce80a04ff99ec2762a8c47f22d/light.png",
"fullCategoryHierarchy": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-000-000",
"name": "General Goods",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-003-000",
"name": "Discount Stores",
"icon": "https://static.v2.spadeapi.com/categories/3fa31bce80a04ff99ec2762a8c47f22d/light.png"
}
]
},
{
"id": "012-011-011-000",
"name": "Optometrists",
"icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png",
"fullCategoryHierarchy": [
{
"id": "012-000-000-000",
"name": "Services",
"icon": "https://static.v2.spadeapi.com/categories/922d5d4ec3a64304a93723bea02d3890/light.png"
},
{
"id": "012-011-000-000",
"name": "Medical and Healthcare Services",
"icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png"
},
{
"id": "012-011-011-000",
"name": "Optometrists",
"icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png"
}
]
},
{
"id": "011-018-002-000",
"name": "Department Stores",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png",
"fullCategoryHierarchy": [
{
"id": "011-000-000-000",
"name": "Retail",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-000-000",
"name": "General Goods",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
},
{
"id": "011-018-002-000",
"name": "Department Stores",
"icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
}
]
},
{
"id": "005-005-000-000",
"name": "Food Delivery Services",
"icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png",
"fullCategoryHierarchy": [
{
"id": "005-000-000-000",
"name": "Food and Drink",
"icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
},
{
"id": "005-005-000-000",
"name": "Food Delivery Services",
"icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
}
]
}
],
"expectedMerchantCategoryCodes": [
{
"code": "5411",
"description": "Grocery Stores, Supermarkets"
},
{
"code": "5541",
"description": "Service Stations ( with or without ancillary services)"
},
{
"code": "5300",
"description": "Wholesale Clubs"
},
{
"code": "5310",
"description": "Discount Stores"
},
{
"code": "8043",
"description": "Opticians, Opticians Goods and Eyeglasses"
},
{
"code": "5968",
"description": "Direct Marketing – Continuity/Subscription Merchant"
},
{
"code": "5542",
"description": "Automated Fuel Dispensers"
},
{
"code": "5912",
"description": "Drug Stores and Pharmacies"
},
{
"code": "7392",
"description": "Management, Consulting, and Public Relations Services"
},
{
"code": "4814",
"description": "Fax services, Telecommunication Services"
},
{
"code": "5999",
"description": "Miscellaneous and Specialty Retail Stores"
},
{
"code": "5969",
"description": "Direct Marketing – Not Elsewhere Classified"
},
{
"code": "5311",
"description": "Department Stores"
},
{
"code": "8042",
"description": "Optometrists and Ophthalmologists"
},
{
"code": "5812",
"description": "Eating places and Restaurants"
},
{
"code": "7800",
"description": "Government-Owned Lotteries"
}
]
}
],
"thirdParties": []
}
Merchant search results are ordered by decreasing similarity to the search query. Up to five counterparties and third parties will be returned. In the next section, we'll discuss the data included in merchant search results in detail.
Understanding merchant search results
In merchant search, merchant results will be returned as counterparties, third parties, or both based on how they appear in enrichments. For more information on the difference between counterparties and third parties, see our Glossary.
Third Party Information
- Third party results contain all the information you would find on a third party returned in an enrichment. This includes id, name, type, logo, website, and similarity, where similarity is a value between 0 and 100 indicating the relevance of the third party to the merchant search query.
Counterparty Information
-
Similar to third party results, counterparty results include ids, names, logos, websites, and similarities along with some important, more granular, attributes.
-
Affiliates: Affiliates are other merchants which Spade believes have a relationship to a counterparty. Take Valero and Circle K, or Dunkin and Baskin-Robbins -- businesses which are often located in the same physical space. You might be interested in creating spending controls that allow transactions at both merchants to be processed, while preventing transactions at other businesses. You can use a counterparty's
affiliatesto make decisions about transactions occurring at related merchants. Each affiliate includes its id, name, logo and website. -
Alternates: Alternates are IDs that have a very low (often less than 1%) chance of being returned during a transaction enrichment at the corresponding counterparty. Along with the ID, we provide a
similarityscore which reflects this ID's likeness to the counterparty. Results are limited to five alternate counterparties. You can use these alternate IDs to dramatically reduce false declines resulting in rules based on counterpartyIDs. -
Spade Categories: Each counterparty includes
expectedSpadeCategories. These are our proprietary categories which appear in enrichments. We analyze our data to determine which Spade Categories are most likely to appear on transactions processed by each merchant. Each Spade Category also includes a list of all its ancestor categories in the fullfullCategoryHierarchyobject. Ancestor categories are more broad than their specific children. Note that a merchant'sexpectedSpadeCategoriesmay change over time as we continue to refine our understanding of what goods and services that merchant provides. -
Merchant Category Codes: Specified by ISO 18245, Merchant Category Codes are widely used to classify the kinds of products or services provided by a business. We derive
expectedMerchantCategoryCodesfrom our data and include those which are most likely to appear in a merchant's transactions. Each MCC includes its code and description. Similarly toexpectedSpadeCategories, MCCs may change over time as we continue to improve our data.
Integrating merchant search into your application
If you intend to integrate merchant search into your application and pass along results to your users, it's essential that you proxy merchant search requests through your backend to Spade's servers. Because client-side code is public and your API key is secret, you will need to proxy merchant search requests through your backend to Spade's servers.
⚠ NEVER send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc...).
Step 1: Set up a proxy endpoint on your backend
For security reasons, you'll first need to set up an endpoint on your backend to act as a middleman between your frontend and Spade's API.
Here's how you might set up this endpoint using Flask:
from flask import Flask, request
from flask_login import login_required
import requests
app = Flask(__name__)
spade_api_key = os.environ.get("SPADE_API_KEY")
@app.get('/merchants')
# Make sure the user is authenticated. Only authenticated users should be able to query Spade's merchant database.
@login_required
def get_merchant_merchants():
# Grab the name from the query parameters (i.e. GET /merchants?name=walmart)
name = request.args.get('name', '')
# Forward the request to Spade
response = requests.get("https://east.sandbox.spade.com/merchants", params={"name": name}, headers={"X-Api-Key": spade_api_key})
# Relay Spade's response to your frontend
return response.json(), response.status_code
Step 2: Add the autocomplete input to your frontend
Now that you have an endpoint to hit, you can add an autocomplete input to your frontend to allow your users to search Spade's merchant database.
Many frameworks and packages provide autocomplete functionality out of the box. Here's an example written in Svelte using the simple-svelte-autocomplete package:
<script>
import AutoComplete from "simple-svelte-autocomplete";
async function getMerchants(name) {
const url = "https://<YOUR_API_DOMAIN_HERE>/merchants?name=" + encodeURIComponent(name);
const response = await fetch(url);
const json = await response.json();
return json.results;
}
</script>
<AutoComplete
searchFunction="{getMerchants}"
delay="400"
localFiltering={false}
labelFieldName="name"
valueFieldName="id"
bind:selectedItem="{selectedMerchant}"
/>;
In this example, we're using the
simple-svelte-autocompletepackage's built-in throttling functionality (this is what thedelay="400"setting configures).Depending on your tech stack, you may need to throttle / debounce requests manually. Because Spade's merchant merchant search API is rate-limited, it is important that you throttle / debounce requests in order to avoid making too many requests.
If your existing tech stack doesn't provide a function to throttle / debounce requests,
lodashis a relatively lightweight package that provides simple functions for throttling and debouncing.
Conclusion
You've just learned how Spade's merchant search endpoint can be used to get detailed merchant information. Now you're ready start making some queries and make fine-grained transaction processing decisions on top of Spade's rich data.