# Merchant Search by Address
source: https://developer.mastercard.com/locations-merchants/documentation/use-cases/merchant-search-by-address/index.md

## 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 **cashback** 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'** , **'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`

<br />

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":"cashback",
  "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",
      "cashbackMaximumAmount": "40",
      "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",
      "cashbackMaximumAmount": "40",
      "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",
      "cashbackMaximumAmount": "40",
      "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",
      "cashbackMaximumAmount": "40",
      "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",
      "cashbackMaximumAmount": "40",
    }
  ]
}
```

## Relevant Endpoints {#relevant-endpoints}

[Merchant Search](https://developer.mastercard.com/locations-merchants/documentation/api-reference/index.md#tag/Merchants/operation/getMerchants)
helps identify Merchant locations corresponding to geographic areas. Turn on the radius search parameters and insert geo-coordinates to transform your search into a rendered list of "nearby" Merchants.

API Reference: `POST /searches`

## Useful Links {#useful-links}

* [View the full Open API Specification](https://developer.mastercard.com/locations-merchants/documentation/api-reference/index.md)
* [Review the APIs error responses](https://developer.mastercard.com/locations-merchants/documentation/code-and-formats/index.md)