Mastercard Searches API

openapi: 3.2.0
info:
  title: Mastercard Merchant Locations Searches API
  description: The Merchants Locations API grants users access to Mastercards extensive merchant data. It can be used to enrich partial addresses, find the precise location of an address, or even a radius search by merchant type.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 2.0.0
servers:
- url: https://api.mastercard.com/locations/merchants
  description: Production server
- url: https://sandbox.api.mastercard.com/locations/merchants
  description: Sandbox server
tags:
- name: Searches
paths:
  /searches:
    post:
      tags:
      - Searches
      summary: Mastercard Get a List of Merchant Details
      description: Returns detailed information on merchants based on the provided query parameters
      operationId: getMerchants
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/DistanceParam'
      - $ref: '#/components/parameters/DistanceUnitParam'
      requestBody:
        $ref: '#/components/requestBodies/MerchantSearch'
      responses:
        '200':
          $ref: '#/components/responses/Merchants'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    DistanceParam:
      name: distance
      in: query
      description: Distance measurement for calculating the radius search. Optional The length of distance from the centroid point. Value string(<25). The default will be 5 units
      required: false
      schema:
        type: integer
      example: 5
    DistanceUnitParam:
      name: distance_unit
      in: query
      description: Unit of measurement for calculating the radius search. Optional. Measurement of distance unit in miles or kilometers. Value string (MILE or KM)
      required: false
      schema:
        type: string
        enum:
        - MILE
        - KM
      example: MILE
    LimitParam:
      name: limit
      in: query
      description: The number of items to be retrieved
      required: false
      schema:
        type: integer
      example: 25
    OffsetParam:
      name: offset
      in: query
      description: The page offset used for the query
      required: false
      schema:
        type: integer
      example: 1
  responses:
    ForbiddenError:
      description: Insufficient permissions for interacting with the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-merchants-api
                ReasonCode: PERMISSION_DENIED
                Description: You don't seem authorized to do that
                Recoverable: false
                Details: Reading merchant information requires read-only permissions
    Merchants:
      description: List of Merchant details
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Merchants'
    UnauthorizedError:
      description: Authentication information was missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: locations-merchants-api
                ReasonCode: UNAUTHORIZED
                Description: We couldn't recognize you
                Recoverable: false
                Details: Full authentication is required to access this resource
    BadRequestError:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            Errors:
            - Error:
                Source: latitude
                ReasonCode: INVALID_INPUT_VALUE
                Description: Latitude is missing, invalid, or could not be determined from address fields.
                Recoverable: false
                Details: null
  schemas:
    Merchants:
      title: Merchants
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: The number of items in the retrieved data set
          example: 10
        limit:
          type: integer
          format: int32
          description: The number of items requested to be retrieved
          example: 10
        offset:
          type: integer
          format: int32
          description: The page offset used for the query
          example: 1
        total:
          type: integer
          format: int32
          description: The total number of merchants available to be retrieved
          example: 210
        merchants:
          type: array
          description: The list of merchants retrieved
          items:
            $ref: '#/components/schemas/Merchant'
          example: []
    Error:
      description: Details of the error condition such as the source of the error, reason code for the error, if the error is recoverable, and details about the error
      required:
      - Description
      - ReasonCode
      - Recoverable
      - Source
      type: object
      properties:
        Source:
          description: The application that generated this error
          type: string
          minLength: 0
          maxLength: 150
          example: latitude
        ReasonCode:
          description: A unique constant identifying the error case encountered during transaction processing
          type: string
          minLength: 0
          maxLength: 150
          example: INVALID_INPUT_VALUE
        Description:
          description: Short description of the ReasonCode field
          type: string
          minLength: 0
          maxLength: 150
          example: Latitude is missing, invalid, or could not be determined from address fields.
        Recoverable:
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
          type: boolean
          example: 'false'
        Details:
          description: Description of the issue
          example: Latitude is missing, invalid, or could not be determined from address fields.
          type:
          - string
          - 'null'
          minLength: 0
          maxLength: 150
    Errors:
      description: Only returned in the event of an error condition
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: An error object
          example:
          - Error:
              Source: latitude
              ReasonCode: INVALID_INPUT_VALUE
              Description: Latitude is missing, invalid, or could not be determined from address fields.
              Recoverable: false
              Details: null
      example:
        Errors:
        - Error:
            Source: latitude
            ReasonCode: INVALID_INPUT_VALUE
            Description: Latitude is missing, invalid, or could not be determined from address fields.
            Recoverable: false
            Details: null
    MerchantSearch:
      title: MerchantSearch
      description: Merchant Search Request Info
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the street address for the merchant location. Usually includes the street number and name. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: 4033 Veterans Memorial Pkwy
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number. This parameter is used rarely and is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter and either City parameter or PostalCode parameter.
          example: Apt 1
        city:
          type: string
          description: The name of the city for a merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: SAINT PETERS
        countryCode:
          type: string
          description: Any two digit country code for a Merchant location. Valid values are two digit alpha country code. This parameter is ignored if latitude and longitude are provided. This parameter is required if any other address information is provided including AddressLine1 AddressLine2 City PostalCode or CountrySubdivision.
          example: USA
        countrySubdivisionCode:
          type: string
          description: The state or province for a merchant location (only supported for US and Canada locations). This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: MO
        latitude:
          type: string
          description: The latitude of a merchant location. If latitude is provided longitude must also be provided.
          example: '38.795089'
        longitude:
          type: string
          description: The longitude of a merchant location. If longitude is provided latitude must also be provided.
          example: '-90.572346'
        merchantCategory:
          type: string
          description: Category Id of the merchant location. See the Categories resource for a list of valid categories.  Input may be a comma delimited list of category ids.
          example: '0'
        merchantType:
          type: string
          description: Type of merchant location. Options are 'paypass' 'repower' 'easysavings' and 'cashback'.
          example: easysavings
        offerMerchantId:
          type: string
          description: Unique identifier that represents the merchant sponsor of an offer. Any valid merchant ID.
          example: '1143109'
        postalCode:
          type: string
          description: The zip code or postal code for a Merchant location. This parameter is ignored if latitude and longitude are provided. If you provide this parameter you must also provide the Country parameter.
          example: '63376'
    Merchant:
      title: Merchant
      description: Merchant detail information
      type: object
      properties:
        addressLine1:
          type: string
          description: Line 1 of the street address for the merchant location. Usually includes the street number and name.
          example: 1 Oak Street
        addressLine2:
          type: string
          description: Line 2 of the street address usually an apartment number or suite number.
          example: Apt 1
        cashbackMaximumAmount:
          type: string
          description: Maximum cashback amount permitted at the location.
          example: '40'
        category:
          type: string
          description: The Merchant Category
          example: 10 - Grocery Stores & Supermarkets
        countryCode:
          type: string
          description: Two digit alpha country code as defined in ISO
          example: US
        countryName:
          type: string
          description: Name of the country.
          example: United States
        countrySubdivisionCode:
          type: string
          description: Code of the state or province for a merchant location.
          example: MO
        countrySubdivisionName:
          type: string
          description: Name of the state or province for a merchant location.
          example: Missouri
        city:
          type: string
          description: The name of the city for a merchant location.
          example: OFallon
        distance:
          type: number
          description: This is the numerical value for the distance from the provided location to the selected merchant.
          format: double
          example: 1.75723000000001
        distanceUnit:
          type: string
          description: This is the unit of measure value for the distance from the provided location to the selected merchant. Options are KM and MILE.
          example: MILE
        easySavingsMerchantOfferId:
          type: string
          description: Merchant's Easy Savings Offer Id
          example: '1143109'
        geocodingResult:
          type: string
          description: GeocodingResult for the merchant
          example: S8HPNTSCZA
        id:
          type: integer
          description: Numerical merchant identifier.
          format: int32
          example: 1505451132
        isPayPassConcession:
          type: boolean
          description: Boolean value which indicates if the concession area is equipped with a PayPass card reader.
          example: true
        isPayPassPharmacy:
          type: boolean
          description: Boolean value which indicates if the pharmacy is equipped with a PayPass card reader.
          example: true
        isPayPassFuelPump:
          type: boolean
          description: Boolean value which indicates if the fuel pump is equipped with a PayPass card reader.
          example: true
        isPayPassTollBooth:
          type: boolean
          description: Boolean value which indicates if the toll booth is equipped with a PayPass card reader.
          example: true
        isPayPassDriveThrough:
          type: boolean
          description: Boolean value which indicates if the drive thru is equipped with a PayPass card reader.
          example: true
        isPayPassRegister:
          type: boolean
          description: Boolean value which indicates if the register is equipped with a PayPass card reader.
          example: true
        isPayPassTicketing:
          type: boolean
          description: Boolean value which indicates if the ticketing area is equipped with a PayPass card reader.
          example: true
        isPayPassVendingMachine:
          type: boolean
          description: Boolean value which indicates if the vending machine is equipped with a PayPass card reader.
          example: true
        isRepowerByCardSwipeSupported:
          type: boolean
          description: Boolean value which indicates if the repower card load type at this merchant supports Card Swipe.
          example: true
        isRepowerByMoneyPakSupported:
          type: boolean
          description: Boolean value which indicates if the repower card load type at this merchant supports MoneyPak.
          example: true
        latitude:
          type: string
          description: The latitude of the merchant
          example: '38.670337'
        locationName:
          type: string
          description: The name of the merchant
          example: QUIK TRIP STORE 1
        longitude:
          type: string
          description: The longitude of the merchant.
          example: '-90.443727'
        phoneNumber:
          type: string
          description: Merchant's phone number
          example: '8165442210'
        postalCode:
          type: string
          description: The postal code of the Merchant location.
          example: '63366'
        websiteUrl:
          type: string
          description: Merchant's website URL address
          example: www.mcdondalds.com
    ErrorResponse:
      description: Only returned in the event of an error condition
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
  requestBodies:
    MerchantSearch:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MerchantSearch'