Enrich one transaction - GET

Find a merchant based on raw transaction data

Start with our guide on how to use MRS to enrich raw transaction data. Note - See the clearResponse property below for options on how MRS should respond when a merchant was not found. If clearResponse is explicitly set to false and a merchant is not found, an empty array will be returned.

get

/api/v3/merchant

Authorizations

Query parameters

typestring · enumrequired

Two possible values: restrictive or extended. restrictive does not return any information from the Google APIs. extended will return information from Google Maps Platform APIs depending on the case.

Options: restrictive, extended

merchant_namestringrequired

Merchant's name for performing the search. It must be longer than 1 character.

locationstring

Merchant's locality name for performing the search. While this parameter is not mandatory, it is highly recommended to include in the request the merchant`s location or a combination of one or more parameters such as postcode, city and country.

If only one field with location information is available the location parameter is recommended to be used instead of the city parameter (see below). The advantage is the location parameter may have some business rules that apply to it. Also, do not include the same field in more than one parameter sent to MRS.

citystring

City name where the search is restricted to. Note that if only one field of location information is available, it is the location parameter (see above) that should be used first. Also, it is not recommended to repeat the same field in more than one parameter.

Example: London

countrystring

A country name or a ISO 3166-1 country code in alpha2, alpha3 or numeric format. While, technically speaking, the country is optional, it is highly recommended to include this information. Otherwise you might get merchants from the wrong country mapped to a transaction. For example a McDonald`s in London, Kentucky instead of London, Ontario or London, England.

Example: GBR

postcodestring

Postal code where the search is restricted to.

mccstring

Merchant Category Code. Merchant Category Classification (MCC) codes are optional but recommended. MRS uses MCCs in various ways to help identify the correct merchant. A key example is MRS uses MCCs to assist in identifying Automated Teller Machine (ATM) transactions. The code for automated cash disbursements is 6011. This is helpful because in some cases, ATMs are not easily identifiable from the merchant description. Also, certain airline, hotel and car rental companies have their own unique MCC code and if an MCC is provided it can help to identify the correct merchant. Finally an MCC can be used as an extra parameter to distinguish between different businesses that might share a name (for example the Metro Department store, Metro Supermarket and Metro Gas Station).

Example: 5411

onlineboolean

A boolean to indicate if a merchant is online. Accepted values are true and false, both lower case. Defaults to false if omitted

latitudenumber

Latitude coordinate from where the search is restricted to. When this parameter is present, a longitude parameter is required.

Example: 51.51694868913037

longitudenumber

Longitude coordinate from where the search is restricted to. When this parameter is present, a latitude parameter is required.

Example: -0.17244443271737944

radiusstring

A string containing the maximum distance in kilometers from the previously specified point, e.g. "12". If this parameter is not present then a default value will be used, which is set in the configuration. If provided, the latitude and longitude parameters are also required

Example: 12

Pattern: ^\d{1,}$

addressstring

Merchant`s address for performing the search.

logo_sizestring · enum · default: 2x

The size of the logo returned. The possible values are 1x (logo width of 96 pixels) or 2x (logo width of 192 pixels). The default is 2x if this parameter is not specified.

Options: 2x, 1x

additionalInfoboolean

true if it is required to get all of the info from the Google APIs. This is set to false by default. Note that setting this parameter to true increases the costs incurred from the Google APIs. The standard level of Google Places API used by MRS is Basic + Contact. Setting this parameter to true changes the type of call to the Basic + Contact + Atmosphere.

defaultLogoboolean

MRS attempts to return logos for the merchants involved in a transaction. For some transactions, MRS is unable to return a logo or image for the merchant. When this is the case MRS is able to provide a category icon instead. If this parameter is set to true then a default category icon is returned. If this parameter is set to false then the default category icons are not returned. The default value for this parameter is true.

clearResponseboolean · default: true

Returns cleaned and parsed transaction data even when no match is found. This parameter is set to true by default. If an MCC code is provided as part of the input, then the response will also provide categorisation. This means transactions have categorisation info returned even if the merchant was not otherwise identified. If ommitted, defaults to true.

languagestring

The language in which Google requests will be made. The data obtained from Google will be returned in this language, if possible, that is: name and geographic data. Note that some fields may not be available in the requested language. See the list of supported languages and their codes.

Example: es

forceCacheableFieldsstring

An optional comma separated list of response fields that will be force returned from our internal sources. This is useful if you want to cache fields such as the name or website during an extended call. Allowed values are: name, website, img, category, categories

Example: name,website

Responses

application/json

application/json

application/json

text/html

application/jsontext/html

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://europe-west2.snowdrop-mrs.com/api/v3/merchant?type=restrictive&merchant_name=text' \
  --header 'X-Api-Key: YOUR_API_KEY'

200

400

401

403

404

500

200

[
  {
    "name": "text",
    "website": "text",
    "position": {
      "type": "Point",
      "coordinates": [
        1
      ]
    },
    "img": "text",
    "logoImg": "text",
    "categoryImg": "text",
    "logoScore": 1,
    "address": "text",
    "postal_code": "text",
    "street_number": "text",
    "route": "text",
    "locality": "text",
    "administrative_area_level_1": "text",
    "administrative_area_level_2": "text",
    "country": "text",
    "phone": "text",
    "rating": 4.1,
    "reviews": {
      "author_name": "A Google User",
      "author_url": "text",
      "profile_photo_url": "text",
      "language": "text",
      "original_language": "text",
      "rating": 1,
      "relative_time_description": "text",
      "text": "text",
      "time": 1,
      "translated": true
    },
    "opening_hours": {
      "open_now": true,
      "periods": [
        {
          "open": {
            "date": "text",
            "day": 1,
            "time": 1700,
            "truncated": true
          },
          "close": {
            "date": "text",
            "day": 1,
            "time": 1700,
            "truncated": true
          }
        }
      ],
      "special_days": [
        {
          "date": "text",
          "exceptional_hours": true
        }
      ],
      "type": "text",
      "weekday_text": [
        "Monday: 9:00 AM – 5:00 PM",
        "Tuesday: 9:00 AM – 5:00 PM",
        "Wednesday: 9:00 AM – 5:00 PM",
        "Thursday: 9:00 AM – 5:00 PM",
        "Friday: 9:00 AM – 5:00 PM",
        "Saturday: Closed",
        "Sunday: Closed"
      ]
    },
    "price_level": 1,
    "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "category": "text",
    "categories": [
      "text"
    ],
    "intermediary": {
      "name": "Paypal",
      "website": "https://www.paypal.com",
      "img": "https://storage.googleapis.com/production-mrs-tm-logos/6273e53abb09494554c93872_2x.png"
    },
    "isClearResponse": false,
    "cachePolicy": {
      "name": "Google",
      "website": "Google",
      "position": "Google",
      "img": "Google",
      "logoImg": "Google",
      "categoryImg": "Google",
      "logoScore": "Google",
      "address": "Google",
      "postal_code": "Google",
      "street_number": "Google",
      "route": "Google",
      "administrative_area_level_1": "Google",
      "administrative_area_level_2": "Google",
      "country": "Google",
      "phone": "Google",
      "opening_hours": "Google",
      "place_id": "Google",
      "category": "Google",
      "categories": "Google",
      "isClearResponse": "MRS"
    },
    "brand": {
      "id": "64b70cd0584b4b1e7ebcf35d",
      "name": "Carrefour Express",
      "img": "https://storage.googleapis.com/production-mrs-brand-logos/6273e357bb09494554c92a5a_2x.png",
      "website": "http://www.carrefour.com/",
      "esg": {
        "participations": []
      },
      "brandCategory": {
        "parentCategory": "Retail & Shopping",
        "categoryGroup": "Retail & Department Stores",
        "categoryType": "Furniture"
      },
      "verifiedInputDate": "2024-09-02T08:46:35.785Z"
    },
    "aggregateLevel": {
      "id": "64b70cd0584b4b1e7ebcf36d",
      "name": "Carrefour",
      "img": "https://storage.googleapis.com/production-mrs-tm-logos/6273e58dbb09494554c93ae3_2x.png",
      "website": "https://www.carrefour.com/"
    },
    "store": {
      "id": "66c78aa32cea1a4463b8c634"
    }
  }
]

A JSON array of merchant results