Places API Reference Application

Table of Contents

• Overview
  • Compatibility
  • References
  • Tutorial
  • Frameworks
• Setup
  • Prerequisites
  • Application Configuration
  • Build and Execute
  • Reference Application Usage
  • Integrating with OpenAPI Generator
• Use Cases
  • Parameters
  • MCC Codes
  • Industry Codes
  • Places
• API Reference
  • Reference App API Reference
  • Places API Reference
• Authentication
  • Mastercard's OAuth Library
• Glossary
• Support
• License

Overview

This project showcases retrieving places, merchant category codes, and merchant industry codes using the Places API. This application illustrates connecting to the Places API using Mastercard's OAuth library, and an OpenAPI generated client.

An optional dependency is a Google Maps Key. If you don't add a Google API key, you'll see an alert when the page loads and "For Development" over the map. This is normal and allows you to see the program without a key in development mode.

When you get to the part about adding APIs, you will need to add the following APIs:

• Maps JavaScript API

See pricing here. At the time of writing users are offered a $200 credit each month and the API costs $7 / 1000 Requests.

Compatibility

• Java 8 or later

References

• Mastercard’s OAuth Signer library
• Using OAuth 1.0a to Access Mastercard APIs

Tutorial

A tutorial can be found here for setting up and using this service.

Frameworks

• Spring
• Thymeleaf
• OpenAPI Generator
• Java 8+
• Maven

Setup

Prerequisites

• Mastercard Developers Account
• A text editor or IDE
• Java 8+
• Spring Boot 2.2+
• Apache Maven 3.3+
• Set up the JAVA_HOME environment variable to match the location of your Java installation.

Application Configuration

1. Follow this credentials quick guide to get the credentials needed to run this application
   • Be sure to add Places to your project.
   • A zip file will be downloaded automatically with your key.
2. Take note of the given consumer key, keyalias, and keystore password given upon the project creation.
3. Extract zip and place the .p12 file in /src/main/resources of the project.
4. Update the properties found in /src/main/resources/application.properties.

application.properties

mastercard.api.base-path=https://sandbox.api.mastercard.com/location-intelligence/places-locator, This is the URL that the application will use to connect to Mastercard. For production usage, just remove sandbox..

Below properties will be required for authentication of API calls.

mastercard.p12.path=, this refers to .p12 file found in the signing key. Place .p12 file at src\main\resources in the project folder then add the filename here. mastercard.consumer.key=, this refers to your consumer key. Copy it from "Keys" section on your project page in Mastercard Developers mastercard.keystore.alias=keyalias, this is the default value of key alias. If it is modified, use the updated one from keys section in Mastercard Developers. mastercard.keystore.pass=keystorepassword, this is the default value of key alias. If it is modified, use the updated one from keys section in Mastercard Developers.

google.maps.api.key, OPTIONAL if you want to show without error messages, just place your api key here.

Build and Execute

1. Run mvn clean install from the root of the project directory.
   • When install is run, the OpenAPI Generator plugin will generate the sources for connecting to the Places API.
2. run java -jar target/location-intelligence-places-reference-app-X.X.X.jar to start the project.
   • Notice: Replace X with version of the reference app.
   • Example: java -jar target/location-intelligence-places-reference-app-1.0.0.jar
3. Navigate to http://localhost:8080/ in your browser.

Reference Application Usage

• Use the map to see locations in the sandbox.
• click on a marker to open more information on the right panel.
• click on right panel to center the marker on the map.

Integrating with OpenAPI Generator

OpenAPI Generator generates API client libraries from OpenAPI Specs. It provides generators and library templates for supporting multiple languages and frameworks.

See also:

• OpenAPI Generator (maven Plugin)
• OpenAPI Generator (executable)
• CONFIG OPTIONS for java

OpenAPI Generator Plugin Configuration

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>4.3.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/places-api-spec.yaml</inputSpec>
                <generatorName>java</generatorName>
                <library>okhttp-gson</library>
                <configurationFile>${project.basedir}/src/main/resources/openapi-config.json</configurationFile>
                <generateApiTests>false</generateApiTests>
                <generateModelTests>false</generateModelTests>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

Use Cases

Parameters

These are the parameters used for the Places API. All parameters are optional.

Name	Type	Default Value	Purpose
offset	int	0	For Pagination; offset is used to offset the start of the list.
limit	int	25	For Pagination; limit is used to limit the number of entities returned
sort	string	+merchantCategoryCode or +industryName	Sorts the results + for ascending, - for descending and any property from the result.

MCC Codes

Get a paginated list of all Merchant Category Codes.

Places API URL	Method	Parameters	Request Model	Response model
/merchant-category-codes	GET	offset, limit, sort	-	PageResponseMerchantCategoryCode

Get information on a specific Merchant Category code.

PlacesAPI URL	Method	Parameters	Request Model	Response model
/merchant-category-codes/mcc-codes/{mccCode}	GET	-	int	MerchantCategoryCode

Industry Codes

Get a paginated list of all Industry Codes.

PlacesAPI URL	Method	Parameters	Request Model	Response model
/merchant-industry-codes	GET	offset, limit, sort	-	PageResponseMerchantIndustryCode

Get information on a specific Industry code.

PlacesAPI URL	Method	Parameters	Request Model	Response model
/merchant-industry-codes/industries/{industryCode}	GET	-	string	MerchantIndustryCode

Places

Get a paginated list of places that fit the search criteria.

PlacesAPI URL	Method	Parameters	Request Model	Response model
/places/searches	POST	offset, limit	PlaceSearchRequest	PageResponsePlaceInfo

Get information on a specific Industry code.

PlacesAPI URL	Method	Parameters	Request Model	Response model
/places/{location_id}	GET	-	int	placeInfo

API Reference

Reference Application API Reference

Reference App URL	Parameters	Reference App Usage	Places Endpoint Used
/places/search	latitude, longitude, country, distanceUnit	Search for all places 5 distanceUnits around lat, long	/places/searches
/places/{locationId}	none	Lists details for a place by location id	/places/{location_id}
/places/merchantCategoryCodes	none	Retrieves 100 Merchant Category Codes	/merchant-category-codes
/places/merchantCategoryCodes/{mccCode}	none	Lists details about Category Code	/merchant-category-codes/mcc-codes/{mccCode}
/places/merchantIndustryCodes	none	Retrieves 101 Merchant Industry Codes	/merchant-industry-codes
/places/merchantIndustryCodes/{industryCode}	none	Lists details about Industry Code	/merchant-industry-codes/industries/{industryCode}

Example Search Request in a rest client (or browser) of your choice: http://localhost:8080/places/search?latitude=38.7463959&longitude=-90.7475983&country=US&distanceUnit=MILE

Places API Reference

See the API Reference page in the documentation.

API Endpoint	Description
Places Search	Search for locations around specific coordinates or using a large set of filterable fields
Get Places Details	List all details for a location based on location id
Get Merchant Category Codes	List all known Merchant Category Codes (mcc)
Merchant Category Code Search	Lists details about Category Code
Get Industry codes	Lists all known Industry Codes
Industry Codes Search	Lists details about Industry Code

Authentication

Mastercard oauth1 Signer Library

This dependency is required to properly call the API.

<dependency>
    <groupId>com.mastercard.developer</groupId>
    <artifactId>oauth1-signer</artifactId>
    <version>1.2.3</version>
</dependency>

Link to the oauth1 library's Github

Looking for other languages?

See the code used in this application to utilize the library.

Found in /src/java/com.mastercard.placesreferenceapplciation.config.ApiClientConfiguration

ApiClient client = new ApiClient();
HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor(logger::info);
loggingInterceptor.level(HttpLoggingInterceptor.Level.BASIC);
try {
    client.setBasePath(basePath);
    client.setHttpClient(
            client.getHttpClient()
                    .newBuilder()
                    .addInterceptor(new OkHttpOAuth1Interceptor(consumerKey, getSigningKey()))
                    .addInterceptor(loggingInterceptor)
                    .build()
    );

    return client;
} catch (Exception e) {
    logger.error("Error occurred while configuring ApiClient", e);
}
return client;

Glossary

Acronym	Meaning
mcc	Merchant Category Codes

Support

If you would like further information, please send an email to [email protected]

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright © 1994-2020, All Rights Reserved by Mastercard.