# Use Cases
source: https://developer.mastercard.com/locations-merchants/documentation/use-cases/index.md
## Merchant Search by GeoCode {#merchant-search-by-geocode}
This API allows customers to obtain a list of merchant details near a given latitude and longitude. In this example we will query for **repower** merchants at a latitude of '40.712947' and longitude of '-74.013443'.
A merchant type **must** be provided. The valid merchant types are **'paypass'** , **repower'** , **'easysavings'** , and **'cashback'**. Search based on multiple merchant types is allowed.
Diagram sequence-location
**Note :** The geolocation *(latitude and longitude)* used in this example is available in the sandbox. Found [here](https://static.developer.mastercard.com/content/locations-merchants/uploads/locations_merchants_sandbox_data.xlsx)
**RESTful POST Request**
API Reference: `POST /searches`
Note: This example we will limit the results set to 5 locations and to a distance of 10 miles
**RESTful Request Parameters**
```javascript
limit=5
distance=10
distance_unit=MILE
```
**RESTful POST Payload**
```json
{
"merchantType":"repower",
"longitude" : "-74.013443",
"latitude" : "40.712947"
}
```
**RESTful Response:**
```json
{
"count": 5,
"limit": 25,
"offset": 0,
"total": 5,
"merchants": [
{
"id": 744352284,
"category": "0 - No Merchant Category Assigned",
"locationName": "RITE AID - GREEN DOT",
"distance": 0.11884249095864968,
"distanceUnit": "MILE",
"addressLine1": "225 LIBERTY ST STE 1",
"addressLine2": "STE 1",
"city": "NEW YORK",
"postalCode": "10281",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.71325",
"longitude": "-74.015676",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744322280,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3526236256660956,
"distanceUnit": "MILE",
"addressLine1": "82 GREENWICH ST",
"city": "NEW YORK",
"postalCode": "10006-2206",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.707857",
"longitude": "-74.013904",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744320774,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3849603595349271,
"distanceUnit": "MILE",
"addressLine1": "140 CHURCH ST",
"city": "NEW YORK",
"postalCode": "10007",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.715696",
"longitude": "-74.007052",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744320310,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3996251041431737,
"distanceUnit": "MILE",
"addressLine1": "111 FULTON ST",
"city": "NEW YORK",
"postalCode": "10038",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.709971",
"longitude": "-74.006903",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744318698,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.4664309139814295,
"distanceUnit": "MILE",
"addressLine1": "311 BROADWAY",
"city": "NEW YORK",
"postalCode": "10007",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.715671",
"longitude": "-74.005297",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true
}
]
}
```
## Merchant Search by Address {#merchant-search-by-address}
This API allows customers to obtain a list of merchant details near a given address. In this example we will query for **repower** merchants near address '285 Fulton St, New York, NY, USA, 10007'.
Diagram sequence-address
A merchant type **must** be provided. The valid merchant types are **'paypass'** , **repower'** , **'easysavings'** , and **'cashback'**. Search based on multiple merchant types is allowed.
**Note :** The address used in this example is available in the sandbox. Found [here](https://static.developer.mastercard.com/content/locations-merchants/uploads/locations_merchants_sandbox_data.xlsx)
**RESTful POST Request**
API Reference: `POST /searches`
Note: This example we will limit the results set to 5 locations and to a distance of 10 miles
**RESTful Request Parameters**
```javascript
limit=5
distance=10
distance_unit=MILE
```
**RESTful POST Payload**
```json
{
"merchantType":"repower",
"addressLine1":"285 Fulton St",
"city":"New York",
"countryCode":"USA",
"countrySubdivisionCode":"NY",
"postalCode":"10007"
}
```
**RESTful Response:**
```json
{
"count": 5,
"limit": 5,
"offset": 0,
"total": 5,
"merchants": [
{
"id": 744352284,
"category": "0 - No Merchant Category Assigned",
"locationName": "RITE AID - GREEN DOT",
"distance": 0.11884249095864968,
"distanceUnit": "MILE",
"addressLine1": "225 LIBERTY ST STE 1",
"addressLine2": "STE 1",
"city": "NEW YORK",
"postalCode": "10281",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.71325",
"longitude": "-74.015676",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744322280,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3526236256660956,
"distanceUnit": "MILE",
"addressLine1": "82 GREENWICH ST",
"city": "NEW YORK",
"postalCode": "10006-2206",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.707857",
"longitude": "-74.013904",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744320774,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3849603595349271,
"distanceUnit": "MILE",
"addressLine1": "140 CHURCH ST",
"city": "NEW YORK",
"postalCode": "10007",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.715696",
"longitude": "-74.007052",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744320310,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.3996251041431737,
"distanceUnit": "MILE",
"addressLine1": "111 FULTON ST",
"city": "NEW YORK",
"postalCode": "10038",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.709971",
"longitude": "-74.006903",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true,
"geocodingResult": "S8HPNTSCZA"
},
{
"id": 744318698,
"category": "0 - No Merchant Category Assigned",
"locationName": "7-ELEVEN",
"distance": 0.4664309139814295,
"distanceUnit": "MILE",
"addressLine1": "311 BROADWAY",
"city": "NEW YORK",
"postalCode": "10007",
"countrySubdivisionName": "NEW YORK",
"countrySubdivisionCode": "NY",
"countryCode": "USA",
"countryName": "UNITED STATES",
"latitude": "40.715671",
"longitude": "-74.005297",
"isRepowerByCardSwipeSupported": true,
"isRepowerByMoneyPakSupported": true
}
]
}
```
## Merchant Category Search {#merchant-category-search}
This API allows customers to obtain a list of merchant categories and associated category ids
Diagram sequence-category
**RESTful GET Request**
API Reference: `GET /categories`
Note: The below response is a subset of categories included in the response. Use the above demo for a full response
**RESTful Response:**
```json
{
"categories": [
{
"categoryName": "Apparel",
"categoryId": "1"
},
{
"categoryName": "Automotive",
"categoryId": "2"
},
{
"categoryName": "Beauty",
"categoryId": "3"
},
...
{
"categoryName": "Vending Machines",
"categoryId": "26"
},
{
"categoryName": "Video/DVD Rental Stores",
"categoryId": "25"
}
]
}
```
## Country Search {#country-search}
This API allows customers to obtain a list of countries and country codes. In this example we will query for countries.
Diagram sequence-country
**RESTful GET Request**
API Reference: `GET /countries`
Note: The below response is a subset of countries included in the response. Use the above demo for a full response **RESTful Response:**
```json
{
"countries": [
{
"countryName": "CANADA",
"countryCode": "CAN"
},
{
"countryName": "UNITED KINGDOM",
"countryCode": "GBR"
},
{
"countryName": "UNITED STATES",
"countryCode": "USA"
}
]
}
```
## Country Subdivision Search {#country-subdivision-search}
This API allows customers to obtain a list of country subdivisions and associated abbreviations. In this example we will query for "USA".
Diagram sequence-subdivision
**RESTful GET Request**
API Reference: `GET /country-subdivisions`
Note: The below response is a subset of countries included in the response. Use the above demo for a full response
**RESTful Response:**
```json
{
"countrySubdivisions": [
{
"countrySubdivisionCode": "AK",
"countrySubdivisionName": "ALASKA"
},
{
"countrySubdivisionCode": "AL",
"countrySubdivisionName": "ALABAMA"
},
...
{
"countrySubdivisionCode": "WI",
"countrySubdivisionName": "WISCONSIN"
},
{
"countrySubdivisionCode": "WV",
"countrySubdivisionName": "WEST VIRGINIA"
},
{
"countrySubdivisionCode": "WY",
"countrySubdivisionName": "WYOMING"
}
]
}
```
## Merchant Names Search {#merchant-names-search}
This API allows customers to retrieve a list of merchant names for various **Merchant** types like '**paypass** ', '**repower** ', '**easysavings** ', and '**cashback** ' based on a provided partial merchant name. In this example, we will search for '**paypass**' merchants with the keyword 'Pizza'.
Diagram sequence-merchant-names
**RESTful GET Request**
API Reference: `GET /merchants-names`
**RESTful Response:**
```json
{
"count": 100,
"limit": 100,
"offset": 1000,
"searchedMerchantName": "Pizza",
"merchantType": "PAYPASS",
"merchantNames": [
"BEAMER'S A1 PIZZA",
"BEANOS PIZZA",
...
"BEST CHOICE PIZZA 2 FOR 1",
"BEST CITY PIZZA",
"BEST FAMOUS PIZZA"
]
}
```
## Feedback Problem Search {#feedback-problem-search}
This API allows customers to obtain a list of feedback problem types for various **Merchant** types like '**paypass** ', '**repower** ', '**easysavings** ', and '**cashback** '. In this example, we will query for '**paypass**'.
Diagram sequence-feedback-types
**RESTful GET Request**
API Reference: `GET /feedback-problems`
**RESTful Response:**
```json
{
"problemTypes": [
{
"problemCode": "CONTACTLESS_NOT_ACCEPTED",
"problemDescription": "Contactless is not accepted",
"requireUserInput": "N"
},
{
"problemCode": "CONTACTLESS_NOT_WORKING",
"problemDescription": "Contactless is not working",
"requireUserInput": "N"
},
{
"problemCode": "CONTACTLESS_NOT_EASILY_ACCESSIBLE",
"problemDescription": "Contactless is not easily accessible",
"requireUserInput": "N"
},
{
"problemCode": "CONTACTLESS_OTHER",
"problemDescription": "Other",
"requireUserInput": "Y"
}
]
}
```
## Customer Feedbacks {#customer-feedbacks}
This API allows customers to provide feedback regarding specific issues/concerns they encountered while using Location Services API.
In this example we will query for **CONTACTLESS_NOT_ACCEPTED** as problemCode.
Diagram sequence-customer-feedbacks
A problemCode and locationId **MUST** be provided. customerFeedbackComment as optional.
**RESTful POST Request**
API Reference: `POST /customer-feedbacks`
**RESTful POST Payload**
```json
{
"problemCode": "CONTACTLESS_NOT_ACCEPTED",
"locationId": "11587971",
"customerFeedbackComment": "No ContactLess Payment available"
}
```
**RESTful Response:**
```json
{
"success": true
}
```
*** ** * ** ***
Note: For a comprehensive list of possible error codes, please see [Location Services Error Codes](https://developer.mastercard.com/locations-merchants/documentation/code-and-formats/index.md#merchant-locations-api-specific-errors)