API ReferenceChangelog
API Reference

Advanced Search Guide

ⓘ Reading Time: 5 mins

⚠

Advanced search is released in beta.

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.

⚠

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 affiliates to 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 full fullCategoryHierarchy object. Ancestor categories are more broad than their specific children. Note that a merchant's expectedSpadeCategories may 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 expectedMerchantCategoryCodes from our data and include those which are most likely to appear in a merchant's transactions. Each MCC includes its code and description. Similarly to expectedSpadeCategories, 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.

Request proxying

⚠ 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/advanced')
# Make sure the user is authenticated. Only authenticated users should be able to query Spade's merchant database.
@login_required
def get_advanced_merchants():
    # Grab the name from the query parameters (i.e. GET /merchants/advanced?name=walmart)
    name = request.args.get('name', '')

    # Forward the request to Spade
    response = requests.get("https://east.sandbox.spade.com/merchants/advanced", 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/advanced?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-autocomplete package's built-in throttling functionality (this is what the delay="400" setting configures).

Depending on your tech stack, you may need to throttle / debounce requests manually. Because Spade's advanced 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, lodash is a relatively lightweight package that provides simple functions for throttling and debouncing.

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.

Additional Resources

Spending Controls Guide