# Quick Start Guide
source: https://developer.mastercard.com/places/documentation/quick-start-guide/index.md
## Overview {#overview}
The Places service provides APIs for accessing a global dataset of detailed information about Mastercard-accepting merchants. This tutorial guides you through onboarding and making your first API call.
Tip:
###### Postman Collections Quick Start {#postman-collections-quick-start}
If you have credentials and are ready to make calls, use the [Postman Collections page](https://developer.mastercard.com/places/documentation/developer-tools/postman-collection/index.md) to work with Sandbox and Production environments without writing code.
> #### You can follow this guide to learn: {#you-can-follow-this-guide-to-learn}
>
> * How to create a project for the service.
> * How Mastercard approaches authentication.
> * How to generate your own API client.
> * How to make calls to the Sandbox or Production environment.
### Checklist {#checklist}
| # | Step | Description |
|---|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access | Create a Mastercard Developers account using an enterprise email ID, or log in with your existing credentials. |
| 2 | Project | Create a Mastercard Developers project and get access to the Places API in the Sandbox environment. |
| 3 | First Call | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a credentials |
| 4 | Validation | Test the Places API in the Sandbox environment with mocked data, positive flows, and negative flows. |
| 5 | Production | After Sandbox validation is complete, use the [Onboarding Checklist](https://developer.mastercard.com/places/documentation/tutorials-and-guides/onboarding-checklist/index.md) to request Production access. |
## Step 1: Get Access to Mastercard Developers Platform {#step-1-get-access-to-mastercard-developers-platform}
If you haven't done so already, you must first create an account with Mastercard Developers.
1. Go to [Mastercard Developers](https://developer.mastercard.com/account/sign-up) and [log in](https://developer.mastercard.com/account/log-in), or create an account using an enterprise email ID.
2. To activate your account, open the link sent to your email address and sign in.
## Step 2: Create a Project and Generate Sandbox Credentials {#step-2-create-a-project-and-generate-sandbox-credentials}
Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox provides mocked data so that you can validate your integration before requesting Production access.
1. To start, log in to your Mastercard Developers account and go to the [My Projects](https://developer.mastercard.com/dashboard) page.
2. Click **Create new project** from the upper right. 
3. Enter a project name.
4. Indicate whether you are creating the project on behalf of a client.
5. In the Select at least one API field, choose Places and click Proceed. 
**Project Credentials**
6. On the Project credentials page, enter a Key alias and Keystore password for your project. Select Proceed. If you have a custom CSR file to use, select Skip this step instead. You'll upload your CSR on your project dashboard after your project is created.
**Additional Credentials**
7. Download your project key zip file containing the .p12 file required for OAuth authentication in Sandbox.
8. Click **Open Project** . 
**Save the values you will need**
9. In the navigation panel on the left, you also have access to areas where you can get your Sandbox and Production credentials and upload a CSR file for your project. You can also manage your project settings and add other team members to your project.
10. After you complete this flow, your project page opens. On the project Summary page, you can see the status of your Sandbox and Production access requests: **Ready** or **Not Requested**. You can also choose to request Production access from this page.
### Import sandbox keys {#import-sandbox-keys}
Open the zip file you downloaded in the previous steps. Import the Sandbox keys (the .p12 file) according to your specific development environment using the Keystore Password for sandbox, which you downloaded as well.
On your project page under **CREDENTIALS \> Sandbox** , you can find the consumer key that applies to your environment. The consumer key is a 97-character string separated by an exclamation mark. The format is `!`. The Mastercard API Client ID is the first 48 characters of this key (``), which uniquely identifies the API caller.
## Step 3: Generate Your Own API Client {#step-3-generate-your-own-api-client}
1. Navigate to the API documentation page.
2. Download the API specification (OpenAPI or Swagger).
3. Generate and configure an API client for this API.
4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries).
For a detailed step-by-step guide, see [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/).
## Step 4: Make your first Sandbox Request {#step-4-make-your-first-sandbox-request}
Once you have Sandbox credentials, run this request and validate the result. This first-call example uses `POST /places/searches`, so you can verify access, OAuth signing, and the Sandbox base URL before moving on. For more information about this endpoint, see the [API Reference](https://developer.mastercard.com/places/documentation/api-reference/index.md).
### Endpoint {#endpoint}
API Reference: `POST /places/searches`
**Path Parameters**
```javascript
limit=25
offset=0
```
**POST Payload**
```json
{
"place": {
"countryCode": "US",
"industry": "EAP",
"geocodeQualityIndicator": "STOREFRONT",
"hasCashBack": false,
"latitude": 38.7468239,
"longitude": -90.7460708
},
"distance": 15,
"radiusSearch": true,
"unit": "MILE"
}
```
**Response:**
A successful call returns HTTP 200 and a JSON object containing matching merchant locations. The example below reports 14 total matches and includes 2 records in the current page, as shown by `total: 14` and `limit: 2`.
```json
{
"total": 14,
"offset": 0,
"limit": 2,
"items": [
{
"merchantName": "HUNAN KING",
"cleansedMerchantName": "KING HUNAN",
"streetAddress": "3038 WINGHAVEN BLVD",
"cleansedStreetAddress": "3038 WINGHAVEN BLVD",
"cityName": "O FALLON",
"cleansedCityName": "O FALLON",
"stateProvinceCode": "MO",
"cleansedStateProvinceCode": "MO",
"postalCode": "63368",
"cleansedPostalCode": "63368-3620",
"countryCode": "US",
"cleansedCountryCode": "US",
"telephoneNumber": "6365617771",
"cleansedTelephoneNumber": "6365617773",
"legalCorporateName": "HUNAN KING",
"cleansedLegalCorporateName": "HUNAN KING",
"industry": "EAP",
"superIndustry": "ACF",
"firstSeenWeek": "08/22/2005-08/28/2005",
"lastSeenWeek": "09/19/2005-09/25/2005",
"isNewBusiness": false,
"isInBusiness7Day": true,
"isInBusiness30Day": true,
"isInBusiness60Day": true,
"isInBusiness90Day": true,
"isInBusiness180Day": true,
"isInBusiness360Day": true,
"hasCashBack": false,
"hasPayAtThePump": false,
"hasNfc": true,
"latitude": 38.749129,
"longitude": -90.748894,
"geocodeQualityIndicator": "STOREFRONT",
"primaryChannelOfDistribution": "b",
"aggregateMerchantId": 5812,
"aggregateMerchantName": "NON-AGGREGATED EATING PLACES RESTAURANTS 5812",
"keyAggregateMerchantId": 5812,
"parentAggregateMerchantId": "10001460",
"parentAggregateMerchantName": "NON-AGGREGATED",
"mccCode": "5812",
"msaCode": "7040",
"naicsCode": "722110",
"dmaCode": "609",
"hasApplePay": false,
"hasAndroidPay": false,
"hasSamsungPay": false,
"posTerminalCount": 3,
"payFacCount30Days": 2,
"payFacCount60Days": 2,
"payFacCount90Days": 1,
"payFacCount180Days": 1,
"payFacCount365Days": 1,
"hasEmv": true,
"isEcommerce": true,
"isBrickAndMortar": true,
"locationId": 418412504
},
{
"merchantName": "BRISTOL #149",
"cleansedMerchantName": "BRISTOL SEAFOOD GRILL",
"streetAddress": "2314 TECHNOLOGY DR",
"cleansedStreetAddress": "2314 TECHNOLOGY DR",
"cityName": "O FALLON",
"cleansedCityName": "O FALLON",
"stateProvinceCode": "MO",
"cleansedStateProvinceCode": "MO",
"postalCode": "63368",
"cleansedPostalCode": "63368-7279",
"countryCode": "US",
"cleansedCountryCode": "US",
"telephoneNumber": "6365919300",
"cleansedTelephoneNumber": "(636) 625-6350",
"legalCorporateName": "WING HAVEN REST PARTNERS",
"cleansedLegalCorporateName": "HOULIHAN'S RESTAURANTS INC.",
"industry": "EAP",
"superIndustry": "ACF",
"firstSeenWeek": "03/15/2004-03/21/2004",
"lastSeenWeek": "04/12/2004-04/18/2004",
"isNewBusiness": false,
"isInBusiness7Day": true,
"isInBusiness30Day": true,
"isInBusiness60Day": true,
"isInBusiness90Day": true,
"isInBusiness180Day": true,
"isInBusiness360Day": true,
"hasCashBack": false,
"hasPayAtThePump": false,
"hasNfc": false,
"latitude": 38.751813,
"longitude": -90.753068,
"geocodeQualityIndicator": "STOREFRONT",
"primaryChannelOfDistribution": "b",
"aggregateMerchantId": 5812,
"aggregateMerchantName": "NON-AGGREGATED EATING PLACES RESTAURANTS 5812",
"keyAggregateMerchantId": 5812,
"parentAggregateMerchantId": "10001460",
"parentAggregateMerchantName": "NON-AGGREGATED",
"mccCode": "5812",
"msaCode": "7040",
"naicsCode": "722110",
"dmaCode": "609",
"cleansedMerchantUrl": "https://www.bristolseafoodgrill.com/",
"hasApplePay": true,
"hasAndroidPay": true,
"hasSamsungPay": true,
"posTerminalCount": 3,
"payFacCount30Days": 3,
"payFacCount60Days": 3,
"payFacCount90Days": 3,
"payFacCount180Days": 3,
"payFacCount365Days": 1,
"hasEmv": true,
"isEcommerce": true,
"isBrickAndMortar": true,
"locationId": 267580167
}
]
}
```
To learn more about the data elements returned, see [Data Elements](https://developer.mastercard.com/places/documentation/tutorials-and-guides/data-elements/index.md).
If you receive a similar JSON array, your credentials and authentication are working correctly. You have now successfully called the Places Search API.
### Test in Sandbox {#test-in-sandbox}
After completing your first successful API call, you are ready to test the full functionality of the Places API in Sandbox.
* You can add additional data fields to your first API call to improve match accuracy. See [data elements](https://developer.mastercard.com/places/documentation/tutorials-and-guides/data-elements/index.md) for more information.
* You can check out our [API Reference](https://developer.mastercard.com/places/documentation/api-reference/index.md) to review full request and response definitions.
### Common Errors During Integration {#common-errors-during-integration}
The following issues are commonly encountered when making your first Places API calls.
| Error | Likely Cause | Recommended Action |
|------------------------|------------------------------------------------------|----------------------------------------------------|
| 401 Unauthorized | OAuth signature, Consumer Key, or keystore issue | Review API Basics authentication setup |
| 403 Forbidden | Project lacks required access | Verify Places API has been enabled for the project |
| MISSING_REQUIRED_INPUT | Required field missing | Validate all mandatory request parameters |
| INVALID_INPUT_VALUE | Invalid latitude, longitude, country code, or format | Verify input values and formats |
## Step 5: Move to Production {#step-5-move-to-production}
### Production Prerequisites {#production-prerequisites}
Before you can request Production access, complete the steps in the Production access prerequisites section on your project Summary page.
1. Verify your company to confirm that it is registered to do business with Mastercard. Follow the [Company Verification guide](https://developer.mastercard.com/platform/documentation/account-management/company-verification/#3-complete-verification) to complete this step.
2. Provide your commercial countries to indicate where your end customers are located for this API integration.
### GO LIVE {#go-live}
1. Within your project, select **Request Production Access** . 
2. On the **Select Plan** page, choose the Free Trial Plan to evaluate real-world Places data or the Enterprise Plan for licensed Production use. Select **Proceed** . 
3. On the **Service details** page, enter the required information, then select **Proceed** . 
4. Review and accept the agreement for the selected plan. 
5. On the **Project credentials** page, enter a key alias and keystore password for your project. Select **Proceed**.
Production credentials are generated immediately, but Mastercard must approve them for Production access before you can go live. After the team reviews your request, you will receive an email from [apisupport@mastercard.com](mailto:apisupport@mastercard.com) confirming whether access was approved or denied.
## Next Steps {#next-steps}
* API Reference: Review the full [API specification](https://developer.mastercard.com/places/documentation/api-reference/index.md).
* Data Elements: To learn more about the merchant location data attributes available, see [Data Elements](https://developer.mastercard.com/places/documentation/tutorials-and-guides/data-elements/index.md).
* Codes and Formats: Review [Error Codes](https://developer.mastercard.com/places/documentation/codes-and-formats/index.md) and their resolution steps.
* Use Cases: See [Use Cases](https://developer.mastercard.com/places/documentation/use-cases/index.md) to learn how clients use the API to create value for their organizations.