# Location Services
source: https://developer.mastercard.com/locations-merchants/documentation/index.md

## Overview {#overview}

The Location Services API is a merchant locator and retail location API that gives applications and websites access to Mastercard merchant-location data for consumer services. It helps product teams find nearby participating merchant locations by geographic coordinates or street address and return structured location and program information, for scenarios such as store locators, click-and-collect, and verifying merchant locations for compliance.
The service supports location discovery for merchant types such as contactless/paypass, Mastercard easySavings and cashback, including cashback retailers, prepaid card reload locations and partner retailers. It also provides supporting lookup and feedback operations for merchant names, merchant category codes (MCC) and category IDs, countries, country subdivisions and merchant-location issues.

Problem This API Solves:

* Help consumers find nearby participating locations. Add merchant-location discovery to a mobile app, website, map or service locator without building a separate location dataset.
* Search with the location information already available. Find merchants using latitude and longitude or a structured street address.
* Guide users to relevant payment-program locations. Filter searches for participating cashback, easySavings or contactless/paypass merchant locations, including reload network locations and rewards merchants.
* Capture inaccurate or outdated location experiences. Retrieve standardized feedback reason codes and submit contactless payment feedback for a specific merchant location.

<br />

## Who It Is For {#who-it-is-for}

Location Services is designed for organizations that rely on accurate location intelligence and merchant context to power their products and decisions:

* Card issuers and digital-banking teams building location discovery into cardholder experiences.
* Fintech and digital-wallet product teams adding nearby merchant search to applications and websites.
* Loyalty and benefits teams guiding eligible users to participating easySavings or cashback locations.
* Developers and integration teams that need structured merchant-location, category and geographic lookup data.

<br />

## How It Works {#how-it-works}

**Real-world scenario:** a traveller staying at a hotel wants to find a boutique within walking distance that offers Cashback. The end user asks the API consumer's app for nearby Cashback locations, the app calls the Location Services API with the user's coordinates and a three-mile radius, the API queries Mastercard's merchant-location database, and the app returns a distance-ordered list of participating merchant locations instantly.

The sequence below shows the request and response flow between the end user, the API consumer application and the Location Services API:
Diagram sequence-address

Step by step:

1. **Request (End User → API Consumer):** the end user asks the API consumer's app or website for participating locations near them, for example "Where are locations that offer Cashback within 3 miles from me?".
2. **Request (API Consumer → Location Services API):** the API consumer sends an OAuth 1.0a signed REST request to the merchant search endpoint, passing the search geocode or address plus the three-mile radius and program filter.
3. **Processing (Location Services API):** the API validates the request and queries Mastercard's merchant-location database for participating merchants matching the location and program criteria.
4. **Response (Location Services API → API Consumer):** the API returns a JSON response with the matching merchant locations, including merchant name, address, geolocation and distance, ordered by distance.
5. **Outcome (API Consumer → End User):** the app displays the results, so the end user instantly sees the nearest participating Cashback boutiques and can navigate to one, without the API consumer building or maintaining its own location dataset.

<br />

## How Location Services Integrates {#how-location-services-integrates}

Location Services is built for simple, scalable integration into existing data pipelines and applications:

* API-first architecture using REST
* Secure authentication via OAuth 1.0a
* Core interaction model:
  * Submit input data (e.g.,latitude, longitude, address etc.)
  * Receive enriched merchant attributes (name, address, geolocation, distance, etc.)
* Use case specific endpoints:
  * [Merchant Search by GeoCode](https://developer.mastercard.com/locations-merchants/documentation/use-cases/merchant-search-by-geocode/index.md)
  * [Merchant Search by Address](https://developer.mastercard.com/locations-merchants/documentation/use-cases/merchant-search-by-address/index.md)
  * [Merchant Names](https://developer.mastercard.com/locations-merchants/documentation/use-cases/merchant-name/index.md)
* Sandbox environment available for testing and evaluation

<br />

Integration at a glance

|        Detail        |                                                                 Description                                                                 |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| Authentication       | OAuth 1.0a                                                                                                                                  |
| Transaction security | The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security) |
| Sandbox URL          | <https://sandbox.api.mastercard.com/locations/merchants>                                                                                    |
| Production URL       | <https://api.mastercard.com/locations/merchants>                                                                                            |
| Data Type            | JSON request and response bodies                                                                                                            |
| Data Refresh         | Data refreshes weekly                                                                                                                       |

## Next Steps {#next-steps}

### Quick Start {#quick-start}

Learn how to go from account setup to make first successful Sandbox request for Location Services

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/quick-start-guide/index.md)

### Get Ready for Production {#get-ready-for-production}

Find out about the stages to progress your integration to production

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/tutorials-and-guides/onboarding-checklist/index.md)

### Explore Capabilities {#explore-capabilities}

Know more about the sample scenarios and how it can be used

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/use-cases/index.md)

### Mastercard API Basics {#mastercard-api-basics}

Find out how to get set up with a project and learn about client authentication.

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/api-basics/index.md)

### Developer Tooling {#developer-tooling}

Use our Postman Collection, Insomnia plug-in, and sample code to accelerate development.

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/developer-tools/index.md)

#### Talk to Us {#talk-to-us}

More questions? Review our FAQ or get in touch.

[Learn more →](https://developer.mastercard.com/locations-merchants/documentation/support/index.md)