# Support
source: https://developer.mastercard.com/places/documentation/support/index.md

## FAQ {#faq}

#### General {#general}

The Places API is a REST-based service that returns cleansed and enriched merchant location data including name, address, geo-coordinates, merchant category, and business attributes sourced from the Mastercard payments network. Developers send search and filter criteria, such as merchant name, geo-coordinates, or a Location ID (sourced from another Mastercard API service, such as [Merchant Identifier API](https://developer.mastercard.com/merchant-identifier/documentation/) and receive a structured JSON response with merchant details. Refer to [How it works](https://developer.mastercard.com/places/documentation/index.md#how-it-works) for more information. The Places API is used to build location-aware applications, cleanse and enrich transaction data, power local search tools, populate merchant directories, and support loyalty and spend-analytics programs. It is commonly used by fintechs, issuers, mapping platforms, and data aggregators. To know more check [Places Use Cases](https://developer.mastercard.com/places/documentation/use-cases/index.md). The Places API returns rich merchant attributes for a known Location ID or geographic search, while the Merchant Identifier (MID) API is most often used to match raw payment transaction data (descriptors or Card Acceptor IDs) to a Mastercard Location ID. The Merchant Identifier API also has an AI-search endpoint for any generic record that is particularly difficult to match (e.g. source data has typos, acronyms, truncations, etc.). These APIs are commonly used together to cleanse and enrich merchant details. Learn more about [Merchant Identifier API](https://developer.mastercard.com/merchant-identifier/documentation/) Yes --- Mastercard offers a 28-day, 10,000-call [free trial](https://developer.mastercard.com/places/documentation/index.md#3-steps-to-access-your-sandbox) of the Places API with no auto-renewal. The trial is designed for developers to evaluate the API against production data before committing to a paid license. Places API pricing follows a per-call model with an annual license minimum. For pricing details, contact your assigned Account Manager or Contact Sales

#### Onboarding {#onboarding}

Sign up at [developer.mastercard.com](https://developer.mastercard.com/account/sign-up), create a project, select the Places API, and download your sandbox key. Once sandbox testing is complete, complete company verification using CID or company details \& request production access via the developer portal. Follow detailed steps on [Quick Start Guide](https://developer.mastercard.com/places/documentation/quick-start-guide/index.md) Once you submit a production access request via the Mastercard Developers portal, approval typically takes 2--3 business days after administrator validation. You'll receive an email confirmation upon approval Yes a Data Evaluation Agreement (DEA) is required for free trial access, and a Statement of Work (SOW) is required for full production licensing. New prospects can start with a click-through DEA signed digitally via Mastercard Developers Places API uses OAuth 1.0a signed with RSA (SHA-256) for authentication. Each request must include a signed authorization header generated using your private key from the developer portal. Learn more → [Authentication Guide](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/) Sandbox and Production URL details are available on [API Basics Page](https://developer.mastercard.com/places/documentation/api-basics/index.md).
* Sandbox

```Sandbox
https://sandbox.api.mastercard.com/location-intelligence/places-locator/
```

* Production

```Production
https://api.mastercard.com/location-intelligence/places-locator/
```

#### Data and Coverage {#data-and-coverage}

The Places API provides global merchant coverage wherever Mastercard is accepted, excluding sanctioned markets (Russia, North Korea, Iran). Expect higher data quality in developed markets such as North America, Europe, South Africa, Australia, and Brazil. Active Mastercard-accepting merchants are included in the dataset. The Places dataset includes over 50 million merchant locations globally across brick-and-mortar and ecommerce channels. The following categories of merchants (by MCC code) are excluded for risk and privacy concerns:

* 8398 - ORGANIZATIONS CHARITABLE AND SOCIAL SERVICES
* 8661 - ORGANIZATIONS RELIGIOUS
* 8099 - HEALTH PRACTITIONERS MEDICAL SRVCS-NOT ELSEWHERE
* 5723 - Firearms and ammunition dealers
* 5973 - Religious goods stores
* 8651 - Organizations political
* 8666 - Religious organizations
Yes, Places covers both brick-and-mortar and ecommerce merchants. Ecommerce-only merchants (e.g., digital-native brands) are represented at their headquarters address and identifiable via the ecom_nsr flag or primary_channel_of_distribution field. To know more about the available field check [Data Elements](https://developer.mastercard.com/places/documentation/tutorials-and-guides/data-elements/index.md) Places API data is refreshed weekly. Newly opened merchants typically enter the dataset 7 to 14 days after accepting their first Mastercard transaction. This lag is introduced to allow for a sufficient cleansing and assignment process, ensuring high accuracy and consistency. The Places API returns merchant name, address, latitude/longitude, MCC (Merchant Category Code), industry, in-business flags, payment acceptance flags (NFC, EMV, contactless), and ecommerce/brick-and-mortar indicators. Check full attribute list on [Data Elements](https://developer.mastercard.com/places/documentation/tutorials-and-guides/data-elements/index.md) The standard Places dataset covers the most recent 12 months of active merchants. Historical data (up to 5 years) is available as a custom request via the Places data feed, priced separately. To know more contact your organization's Account Manager or contact sales

#### Integration and Troubleshooting {#integration-and-troubleshooting}

The Places API offers two primary endpoints: Places Search (returns merchants near a lat/long or within a radius) and Location ID Lookup (returns full attribute details for a given Location ID). Search supports a maximum radius of 15 miles. Learn more about the endpoints on [API Reference](https://developer.mastercard.com/places/documentation/api-reference/index.md) The target average response time is less than 1 second, though this varies by query complexity. We recommend setting the client-side timeout to 60 seconds to accommodate edge cases. The Places API uses synthetic monitoring to continuously verify that the API is available and functioning as expected. This information is publicly available, allowing you to check uptime and review any recent issues. Check the [Status Page](https://developer.mastercard.com/api-status?environment=production&service=Locations%20Intelligence%20-%20Places) to view this information. This error indicates you have exceeded the maximum requests allowed within the current time window. Reduce your request rate, implement client-side throttling, or contact Support to review your license tier. The country code you provided is not a valid ISO 3166 Alpha-2 code (e.g., US, GB, FR). Verify your input against the ISO 3166 standard and retry. To know more about the API specific errors check [Codes and Formats](https://developer.mastercard.com/places/documentation/codes-and-formats/index.md) Latitude must be between -90 and 90, and longitude must be between -180 and 180. Ensure decimal precision and remove any formatting characters before retrying. To know more about the API specific errors check [Codes and Formats](https://developer.mastercard.com/places/documentation/codes-and-formats/index.md) Typically one or two calls --- one to the Merchant Identifier API to resolve the merchant's Location ID, and optionally a second call to the Places API to retrieve full attribute details. Clients can cache responses to minimize call volume. Learn more about the [transaction cleansing flow](https://developer.mastercard.com/merchant-identifier/documentation/) Yes, a free 28-day trial with 10,000 production calls is available via self-service signup on Mastercard Developers. You can also test integration flows using the Insomnia plugin for Mastercard APIs. Check [Developer Tools](https://developer.mastercard.com/places/documentation/developer-tools/index.md) to know more. For gateway/authentication errors, refer to the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes). For Places-specific issues, submit a case at developer.mastercard.com/support.

#### Common causes: {#common-causes}

* Your consumer key does not match the one in your Mastercard Developers project.
* Your .p12 signing key file password is incorrect or the file is corrupted.
* The OAuth timestamp is too far from the server time (must be within 5 minutes).
* The request body was modified after the OAuth signature was computed.

#### Step-by-step solution: {#step-by-step-solution}

1. Go to your [Mastercard Developers](https://developer.mastercard.com/dashboard) project page and verify your consumer key.
2. Re-download your .p12 keystore file and confirm the password is correct.
3. Ensure your system clock is synchronized.
4. If using a custom HTTP client, verify the OAuth signature is computed over the exact request body being sent.
5. Test with the [Postman Collection](https://developer.mastercard.com/places/documentation/developer-tools/postman-collection/index.md) to isolate whether the issue is in your signing implementation. See [Codes and Formats](https://developer.mastercard.com/places/documentation/codes-and-formats/index.md) for more details.

## Get Help {#get-help}

### Contact us for technical support. {#contact-us-for-technical-support}