# Use Cases
source: https://developer.mastercard.com/locations/documentation/use-cases/index.md

## ATM Search by GeoCode {#atm-search-by-geocode}

This API allows customers to obtain a list of ATM Location details near a given latitude and longitude. In this example we will query for ATMs at a latitude of '40.712947' and longitude of '-74.013443'.
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/uploads/locations_atms_sandbox_data.xlsx)

**RESTful POST Request**


API Reference: `POST /searches`

<br />

Note: This example we will limit the results set to 5 location and to a distance of 10 miles

**RESTful Request Parameters**

```javascript
 limit=5
 distance=10
 distance_unit=MILE
```

**RESTful POST Payload**

```json
{
    "longitude" : "-74.013443",
    "latitude" : "40.712947"
}
```

**RESTful Response:**

```json
{
  "count": 5,
  "limit": 5,
  "offset": 0,
  "total": 12,
  "atms": [
    {
      "accessFees": "DOMESTIC_AND_INTERNATIONAL",
      "addressLine1": "7 WORLD TRADE CTR",
      "atmTerminalId": "AC006309",
      "availability": "UNKNOWN",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.08774582730276924,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713289",
      "locationName": "CITIBANK",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.01183",
      "owner": "CITIBANK",
      "postalCode": "10007",
      "sponsor": "FISERV SOLUTIONS, LLC",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "88024",
      "routeTransactionNumber": "842548238"
    },
    {
      "accessFees": "UNKNOWN",
      "addressLine1": "225 LIBERTY ST STE 1",
      "atmTerminalId": "RA000943",
      "availability": "UNKNOWN",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.08956877019103475,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "UNKNOWN",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "YES",
      "latitude": "40.712415",
      "locationName": "RITE AID",
      "locationType": "RETAIL_STORE",
      "longitude": "-74.015002",
      "owner": "ALLPOINT",
      "postalCode": "10281",
      "sponsor": "ALLPOINT NETWORK",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "ALLPOINT_PREPAID",
      "sponsorICA": "2000579",
      "routeTransactionNumber": "840491031"
    },
    {
      "accessFees": "DOMESTIC_AND_INTERNATIONAL",
      "addressLine1": "200 VESEY ST 8TH FL",
      "atmTerminalId": "T309B776",
      "availability": "BUSINESS_HOURS",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09309857355313111,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "IS_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.71393",
      "locationName": "CITY NATIONAL BANK",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.014658",
      "owner": "0309-CITY NATIONAL BANK",
      "postalCode": "10281",
      "sponsor": "FIDELITY INFORMATION SERVICES, INC.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "88109",
      "routeTransactionNumber": "124312535"
    },
    {
      "accessFees": "DOMESTIC",
      "addressLine1": "185 GREENWICH ST UNIT LL5107",
      "atmTerminalId": "NY2132",
      "availability": "BUSINESS_HOURS",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09650006934863571,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713359",
      "locationName": "ONE WORLD TRADE CENTER",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.011683",
      "owner": "JPMORGAN CHASE",
      "postalCode": "10007",
      "sponsor": "JPMORGAN CHASE BANK, N.A.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "5883",
      "ownerICA": "5883",
      "routeTransactionNumber": "840605018"
    },
    {
      "accessFees": "DOMESTIC",
      "addressLine1": "185 GREENWICH ST",
      "atmTerminalId": "NY2505",
      "availability": "ALWAYS_AVAILABLE",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09650006934863571,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713359",
      "locationName": "WORLD TRADE CENTER - REMOTE ATMS",
      "locationType": "OTHER",
      "longitude": "-74.011683",
      "owner": "JPMORGAN CHASE",
      "postalCode": "10007",
      "sponsor": "JPMORGAN CHASE BANK, N.A.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "5883",
      "ownerICA": "5883",
      "routeTransactionNumber": "840605018"
    }
  ]
}
```

Tip: You can now enhance your search by applying any of the optional filters listed below, making it easier to find the ATMs that best match your needs. These filters are available for both GeoCode ATM Search and Address ATM Search.

| Optional Filters API Field Name |                          Available Options                           |
|---------------------------------|----------------------------------------------------------------------|
| **accessFees**                  | NO_FEE, DOMESTIC; INTERNATIONAL, DOMESTIC_AND_INTERNATIONAL, UNKNOWN |
| **availability**                | ALWAYS_AVAILABLE, BUSINESS_HOURS, IRREGULAR_HOURS, UNKNOWN           |
| **handicapAccessible**          | IS_HANDICAP_ACCESSIBLE, NOT_HANDICAP_ACCESSIBLE, UNKNOWN             |
| **hasSharedDeposit**            | YES, NO                                                              |
| **isSurchargeFreeAlliance**     | YES, NO                                                              |
| **locationName**                | Direct Name, e.g. "U.S. BANK NATIONAL ASSOCIATION, ND"               |
| **locationType**                | FINANCIAL_INSTITUTION, AIRPORT, GAS_STATION, DRIVE_UP_ATM, etc       |
| **supportsEmv**                 | SUPPORTS_EMV, DOES_NOT_SUPPORT_EMV, UNKNOWN                          |

**RESTful POST Payload with Optional Filters**

```json
{
    "longitude" : "-74.013443",
    "latitude" : "40.712947", 
    "accessFees": "DOMESTIC",
    "availability": "ALWAYS_AVAILABLE", 
    "handicapAccessible": "IS_HANDICAP_ACCESSIBLE", 
    "hasSharedDeposit": "YES", 
    "isSurchargeFreeAlliance": "YES", 
    "locationName": "WORLD TRADE CENTER - REMOTE ATMS", 
    "locationType": "SPORTS_COMPLEX", 
    "supportsEmv": "SUPPORTS_EMV"
}
```

## ATM Search by Address {#atm-search-by-address}

This API allows customers to obtain a list of ATM location details near a given address. In this example we will use address '285 Fulton St, New York, NY, USA, 10007'.
Diagram sequence-address

**Note :** The address used in this example is available in the sandbox. Found [here](https://static.developer.mastercard.com/content/locations/uploads/locations_atms_sandbox_data.xlsx)

**RESTful POST Request**


API Reference: `POST /searches`

<br />

Note: This example we will limit the results set to 5 location and to a distance of 10 miles

**RESTful Request Parameters**

```javascript
 limit=5
 distance=10
 distance_unit=MILE
```

**RESTful POST Payload**

```json
{
  "addressLine1":"285 Fulton St",
  "city":"New York",
  "countryCode":"USA",
  "countrySubdivisionCode":"NY",
  "postalCode":"10007"
}  
```

**RESTful Response:**

```json
{
  "count": 5,
  "limit": 5,
  "offset": 0,
  "total": 12,
  "atms": [
    {
      "accessFees": "DOMESTIC_AND_INTERNATIONAL",
      "addressLine1": "7 WORLD TRADE CTR",
      "atmTerminalId": "AC006309",
      "availability": "UNKNOWN",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.08774582730276924,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713289",
      "locationName": "CITIBANK",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.01183",
      "owner": "CITIBANK",
      "postalCode": "10007",
      "sponsor": "FISERV SOLUTIONS, LLC",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "88024",
      "routeTransactionNumber": "842548238"
    },
    {
      "accessFees": "UNKNOWN",
      "addressLine1": "225 LIBERTY ST STE 1",
      "atmTerminalId": "RA000943",
      "availability": "UNKNOWN",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.08956877019103475,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "UNKNOWN",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "YES",
      "latitude": "40.712415",
      "locationName": "RITE AID",
      "locationType": "RETAIL_STORE",
      "longitude": "-74.015002",
      "owner": "ALLPOINT",
      "postalCode": "10281",
      "sponsor": "ALLPOINT NETWORK",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "ALLPOINT_PREPAID",
      "sponsorICA": "2000579",
      "routeTransactionNumber": "840491031"
    },
    {
      "accessFees": "DOMESTIC_AND_INTERNATIONAL",
      "addressLine1": "200 VESEY ST 8TH FL",
      "atmTerminalId": "T309B776",
      "availability": "BUSINESS_HOURS",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09309857355313111,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "IS_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.71393",
      "locationName": "CITY NATIONAL BANK",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.014658",
      "owner": "0309-CITY NATIONAL BANK",
      "postalCode": "10281",
      "sponsor": "FIDELITY INFORMATION SERVICES, INC.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "88109",
      "routeTransactionNumber": "124312535"
    },
    {
      "accessFees": "DOMESTIC",
      "addressLine1": "185 GREENWICH ST UNIT LL5107",
      "atmTerminalId": "NY2132",
      "availability": "BUSINESS_HOURS",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09650006934863571,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713359",
      "locationName": "ONE WORLD TRADE CENTER",
      "locationType": "FINANCIAL_INSTITUTION",
      "longitude": "-74.011683",
      "owner": "JPMORGAN CHASE",
      "postalCode": "10007",
      "sponsor": "JPMORGAN CHASE BANK, N.A.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "5883",
      "ownerICA": "5883",
      "routeTransactionNumber": "840605018"
    },
    {
      "accessFees": "DOMESTIC",
      "addressLine1": "185 GREENWICH ST",
      "atmTerminalId": "NY2505",
      "availability": "ALWAYS_AVAILABLE",
      "camera": "NO",
      "countryCode": "USA",
      "countryName": "UNITED STATES",
      "countrySubdivisionCode": "NY",
      "countrySubdivisionName": "NEW YORK",
      "city": "NEW YORK",
      "distance": 0.09650006934863571,
      "distanceUnit": "MILE",
      "geocodingResult": "S8HPNTSCZA",
      "handicapAccessible": "NOT_HANDICAP_ACCESSIBLE",
      "hasSharedDeposit": "NO",
      "isSurchargeFreeAlliance": "NO",
      "latitude": "40.713359",
      "locationName": "WORLD TRADE CENTER - REMOTE ATMS",
      "locationType": "OTHER",
      "longitude": "-74.011683",
      "owner": "JPMORGAN CHASE",
      "postalCode": "10007",
      "sponsor": "JPMORGAN CHASE BANK, N.A.",
      "supportsEmv": "SUPPORTS_EMV",
      "surchargeFreeAllianceNetwork": "DOES_NOT_PARTICIPATE_IN_SFA",
      "sponsorICA": "5883",
      "ownerICA": "5883",
      "routeTransactionNumber": "840605018"
    }
  ]
}
```

## 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`

<br />


Note: The below response is a sub-set of countries included in the response. Use the above demo for a full response **RESTful Response:**

<br />

```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`

<br />

Note: The below response is a sub-set 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"
    }
  ]
}
```

## Feedback Problems Search {#feedback-problems-search}

This API allows customers to obtain a list of feedback problem types for **ATM** locations.
Diagram sequence-feedback-types

**RESTful GET Request**


API Reference: `GET /feedback-problems`

<br />

**RESTful Response:**

```json
{
  "problemTypes": [
    {
      "problemCode": "ATM_NOT_PRESENT",
      "problemDescription": "ATM not present",
      "requireUserInput": "N"
    },
    {
      "problemCode": "ATM_BROKEN",
      "problemDescription": "ATM broken",
      "requireUserInput": "N"
    },
    {
      "problemCode": "ATM_DOES_NOT_ACCEPT_MASTERCARD",
      "problemDescription": "ATM doesn't accept MasterCard",
      "requireUserInput": "N"
    },
    {
      "problemCode": "ATM_NOT_ACCESSIBLE",
      "problemDescription": "ATM is not accessible",
      "requireUserInput": "N"
    },
    {
      "problemCode": "ATM_OTHER",
      "problemDescription": "Other",
      "requireUserInput": "Y"
    }
  ]
}
```

## Customer Feedbacks {#customer-feedbacks}

This API allows customers to provide feedback regarding specific issues/concerns they encountered while using ATM Locations. In this example we will query for **ATM_NOT_PRESENT** as problemCode.
Diagram sequence-customer-feedbacks

A problemCode and locationId **MUST** be provided.

**RESTful POST Request**


API Reference: `POST /customer-feedbacks`

<br />

**RESTful POST Payload**

```json
{
  "problemCode": "ATM_NOT_PRESENT",
  "locationId": "11587971",
  "customerFeedbackComment": "No ATM present"
}  
```

**RESTful Response:**

```json
{
  "success": true
} 
```

*** ** * ** ***

Note: For a comprehensive list of possible error codes, please see [ATMs Locations Error Codes](https://developer.mastercard.com/locations/documentation/code-and-formats/index.md#atm-location-api-specific-errors)