Locations

Summary

With Bud's enrichment services, you can identify the location of your customers' transactions. When ingesting data either via the first party ingester or our Connect product your transactions will be run through our various enrichment models before being returned. Our locations enrichment works by matching the merchant and locations tokens identified from our entities model against the millions of locations in our database. Tokens are useful pieces of information about a transaction that has been identified within the transaction description and other associated fields.

🚧

Locations is a premium enrichment which incurs its own cost. Without the locations enrichment you will only receive the location tokens -- in the example below, it would be ["old st", "ldn"].

Exact matches

In instances where we have been able to find an exact match for the location, we will return both a full street address and the latitude and longitude of the location. In addition to this, we will also add a geospatial tag to the transaction so that you know it has a physical location. An example of an enriched transaction with an exact match can be seen below.

{
  "operation_id": "v2_transactions_get",
  "data": [
    {
      "transaction_id": "fbdc28e82f0f137586a526a88ec4a6be",
      "account_id": "5bd9ecaf31fc2d5172fd89cb61b89fc6",
      "provider": "BankOfBud",
      "description": "paypal* specialty coffee",
      "credit_debit_indicator": "debit",
      "status": "booked",
      "amount": {
        "value": "10.99",
        "currency": "GBP"
      },
      "date_time": "2024-02-28T10:00:00Z",
      "enrichments": {
        "categories": {
          "l1": {
            "slug": "eating_out",
            "confidence": "0.99"
          },
          "l2": {
            "slug": "cafes_and_eating_out",
            "confidence": "0.98"
          }
        },
        "merchant": {
          "id": "01cc2d49-6144-46f1-9414-67c99b139a95",
          "slug": "specialty_coffee",
          "display_name": "Specialty Coffee Supplier Ltd.",
          "logo": "http://url/specialtycoffeesupplierltd_logo.jpeg",
          "tokens": [
            {
              "value": "speciality coffee",
              "confidence": "0.98"
            }
          ]
        },
        "location": {
          "address": {
            "address_lines": [
              "101 old street",
              "london",
              "EC1V 9NQ"
            ],
            "country": "uk"
          },
          "geolocation": {
            "latitude": 51.526162, 
            "longitude": -0.084338
          },
          "tokens": [
            "old st",
            "ldn"
          ]
        },
        "processor": {
          "id": "18f63293-0217-4520-bbf0-071dca7a9d04",
          "slug": "paypal",
          "display_name": "PayPal",
          "logo": "http://url/paypal_logo.jpeg",
          "tokens": [
            {
              "value": "paypal",
              "confidence": "0.92"
            }
          ]
        },
        "regularity": {
          "frequency": "monthly",
          "predicted_date_times": [
            "2024-03-28T15:00:00Z",
            "2024-04-28T15:00:00Z",
            "2024-05-28T15:00:00Z"
          ],
          "group_label": "cbba80fb-e02b-48c9-a0df-41d483fc6bc0"
        },
        "transaction_types": [
          "card",
          "debit"
        ]
      },
      "tags": [
        "regular-transaction",
        "geospatial"
      ]
    }
  ]
}

By providing both the full street address and the latitude and longitude you can easily display the written address to your customers or place a pin on a map showing where the transaction took place.

Multiple matches

There may be instances where we cannot find an exact match for the location, in these situations we will return the most specific address details that are common across all of our found matches. For example, this may be the street name without a number, or it could be the town/city where the transaction took place.

Online transactions

For online transactions such as with Amazon or a Netflix subscription, we will add an online tag to the transaction so that you know there is no physical address associated with the transaction. An example of this can be seen below.

{
  "operation_id": "v2_transactions_get",
  "data": [
    {
      "transaction_id": "fbdc28e82f0f137586a526a88ec4a6be",
      "account_id": "5bd9ecaf31fc2d5172fd89cb61b89fc6",
      "provider": "BankOfBud",
      "description": "netflix 2322424 ca us",
      "credit_debit_indicator": "debit",
      "status": "booked",
      "amount": {
        "value": "10.99",
        "currency": "GBP"
      },
      "date_time": "2022-05-28T10:00:00Z",
      "enrichments": {
        "categories": {
          "l1": {
            "slug": "media_and_telecoms",
            "confidence": "0.99"
          },
          "l2": {
            "slug": "tv_streaming_services",
            "confidence": "0.98"
          }
        },
        "merchant": {
          "id": "01cc2d49-6144-46f1-9414-67c99b139a95",
          "slug": "netflix",
          "display_name": "Netflix",
          "logo": "http://url/netflix_logo.jpeg",
          "tokens": [
            {
              "value": "netflix",
              "confidence": "1.00"
            }
          ]
        },
        "location": {
          "tokens": [
            "ca",
            "us"
          ]
        },
        "processor": {
          "id": "18f63293-0217-4520-bbf0-071dca7a9d04",
          "slug": "paypal",
          "display_name": "PayPal",
          "logo": "http://url/paypal_logo.jpeg",
          "tokens": [
            {
              "value": "paypal",
              "confidence": "0.92"
            }
          ]
        },
        "transaction_types": [
          "card",
          "debit"
        ]
      },
      "tags": [
        "online"
      ]
    }
  ]
}

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.