Enrich one transaction - GET

Find a merchant based on raw transaction data

get

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.

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.

Possible values:

merchant_namestringRequired

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

locationstringOptional

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.

citystringOptional

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

countrystringOptional

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

postcodestringOptional

Postal code where the search is restricted to.

mccstringOptional

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

onlinebooleanOptional

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

latitudenumberOptional

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

Example: 51.51694868913037

longitudenumberOptional

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

Example: -0.17244443271737944

radiusstringOptional

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: 12Pattern: ^\d{1,}$

addressstringOptional

Merchant`s address for performing the search.

logo_sizestring · enumOptional

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.

Default: 2xPossible values:

additionalInfobooleanOptional

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.

defaultLogobooleanOptional

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.

clearResponsebooleanOptional

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.

Default: true

languagestringOptional

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

forceCacheableFieldsstringOptional

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

200

A JSON array of merchant results

application/json

400

Returned when the request is malformed. Double check that you are sending the correct parameters in the request, and that they are valid. This error is also thrown when a trial account has expired or exceeded its usage limits.

application/json

401

Returned when the API key is invalid. Double check that you are sending the correct API key in the `X-Api-Key` header.

application/json

403

Returned when the API key is missing. Double check that you are sending the API key in the `X-Api-Key` header.

text/html

404

Returned when the endpoint is not found. Double check that you are sending the request to the correct endpoint.

application/jsontext/html

500

Returned when the request has failed due to an internal server error. Please retry the request later.

application/json

get

HTTPcURLJavaScriptPython

GET /api/v3/merchant HTTP/1.1
Host: europe-west2.snowdrop-mrs.com
X-Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "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"
    }
  }
]