ⓘ Reading Time: 5 mins
Advanced search allows you to query Spade's database for detailed merchant information. Using advanced 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.
We recommend taking a look at our Merchant Search guide to get familiar with the basics of Spade's search products.
Advanced search is not enabled by default. To request access, please contact us at [email protected].
Getting started
You can use advanced search to retrieve all the information available from Spade's merchant search API and much more. Let's try sending the following request to the /merchants/advanced endpoint.
import requests
response = requests.get("https://east.sandbox.spade.com/merchants/advanced", 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"
}
],
"expectedSpadeCategories": [
{
"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": "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"
}
]
}
],
"expectedMerchantCategoryCodes": [
{
"code": "5411",
"description": "Grocery Stores, Supermarkets"
},
{
"code": "5542",
"description": "Automated Fuel Dispensers"
},
{
"code": "5310",
"description": "Discount Stores"
},
{
"code": "5541",
"description": "Service Stations ( with or without ancillary services)"
},
{
"code": "5968",
"description": "Direct Marketing – Continuity/Subscription Merchant"
}
]
}
],
"thirdParties": []
}
Advanced 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 advanced search results in detail.
Understanding advanced search results
In advanced 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 advanced 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. -
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 advanced search into your application
If you intend to integrate advanced search into your application and pass along results to your users, it's essential that you proxy advanced 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 advanced search requests through your backend to Spade's servers. The Merchant Search Guide demonstrates how to proxy requests through your backend to Spade's API.
⚠ NEVER send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc...).
Conclusion
You've just learned how Spade's advanced 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.