Introduction to APIs from Pitney Bowes

Share this post:

The APIs you choose make a difference. You’ll need to harness the power of “where” to optimize inputs and outcomes. Location provides the most consistent way to link people, places and things. While other things may change, the locations themselves stay the same.

For precise, reliable location data, your data sources should add fixed coordinates to each address (a process called geocoding). Geocodes provide a solid point of reference despite the shifting landscape and are the foundation for ensuring the accuracy of related data. They make it easy to connect across datasets, and they make a big contribution to data quality.

Pitney Bowes logoPitney Bowes is an industry leader in geocoding, geodata and location intelligence. Developers can now access our APIs on IBM Bluemix. Each of our APIs is carefully built for quality and purpose and backed with curation and support. The data we provide powers critical use cases in industries like insurance and banking and is also increasingly used in mobile and IoT (Internet of Things) applications worldwide.

Get started with Pitney Bowes and Bluemix

To get started using Pitney Bowes on Bluemix, we’ve put together step-by-step instructions for you to follow. In just a few minutes, you can build and deploy applications with location intelligence functionality.

Before you begin, you’ll need to sign up for a free 30-day trial of IBM Bluemix. Once you’ve signed up, you’ll want to create a new application using the Java web application template.

To get started, follow the instructions below.

While you are logged in to your new Bluemix account, create a new Java application.Screen shot of Create Java app window

Select the Java starter template (Liberty for Java) as shown below.Screen shot of Cloud Foundry Runtimes window

In the Create a Cloud Foundry Application window, create a unique name for your app in the App name field.Create Cloud Foundry App - Give your app a name

Next, you’ll need to download the starter code. This is a sample Java web application which will be downloaded to your computer.Screen shot of the Download Starter Code window

As we mentioned earlier, Pitney Bowes APIs enable the addition of enterprise-class geodata and commerce functionality in your application. Now that your application is created, you’ll want to add the Pitney Bowes APIs. You’ll be using the Pitney Bowes APIs to enhance your location data with addresses, place names, business listings and time zones.

From Bluemix, you need to select “Create Service” to begin creating your new app, as shown below.Screen shot of Create Service in Bluemix window

Then, you should choose APIs from Pitney Bowes from the list of services under the “Services” heading in the Bluemix Catalog, like in the example below.Screen shot of the Bluemix Catalog

Next, you will need to choose the Free Plan or one of the Paid plans,  and then click Create.Screen shot of Pitney Bowes API plans

To interact with Bluemix and deploy your application, you’ll need to download and install the Cloud Foundry command line interface. After we install it we can use the cf login command to connect to the Bluemix environment:


Then, login to Bluemix. This command will ask for your credentials.

cf login


Building your Java application

Now that you’ve got your Bluemix foundation in place, you can get started writing your Java application. First, make sure you have your Java development environment ready. You can also connect with Cloud Foundry by using the Eclipse plugin. Once you’ve setup your Java environment, download the sample project template from Bluemix.

You will need to get your API Key & Secret to get an Auth Token so you can use them in your library. Bluemix handles storing all your service credentials, so you can access these within the VCAP_SERVICES environment variable.

You will have to download LocationIntelligenceSDK for Java . This SDK facilitates you to build innovative, location-rich, Java-based apps using Location Intelligence APIs. You need to include LocationIntelligenceSDK into the Java Starter Project.

Update SimpleServlet class in the Java Starter project as below.

package wasdev.sample.servlet;

import java.util.Iterator;
import java.util.Map;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.pb.locationintelligence.common.model.ErrorInfo;
import com.pb.locationintelligence.common.model.Locations;
import com.pb.locationintelligence.exception.SdkException;
import com.pb.locationintelligence.geoenhance.GeoEnhanceServiceImpl;
import com.pb.locationintelligence.manager.LIServiceManager;
import com.pb.locationintelligence.utils.Utility;
import org.json.JSONArray;
import org.json.JSONObject;

* Servlet implementation class SimpleServlet
public class SimpleServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
String apiKey=null,apiSecret=null;

     * @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse response)

   public void init()
Map<String, String> env;
String vcap;
JSONObject jsonProperties, credentials;

env = System.getenv();
vcap = env.get(“VCAP_SERVICES”);
System.err.println(“VCAP_SERVICE STRING “+vcap);
try {
JSONObject vcap_services = new JSONObject(vcap);
Iterator iter = vcap_services.keys();

if (vcap == null) {
System.err.println(“ContextListener: No VCAP_SERVICES found!”);

while (iter.hasNext()) {
String key = (String);

if (key.startsWith(“pitneybowes-apis”)) {
JSONArray array = vcap_services.getJSONArray(key);
System.out.println(“array “+array);
JSONObject obj = array.getJSONObject(0);
credentials = obj.getJSONObject(“credentials”);
apiKey = credentials.getString(“apiKey”);
apiSecret = credentials.getString(“apiSecret”);



} catch (Exception e) {

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

if (apiKey == null || apiSecret == null) {
System.err.println(“ContextListener: Fatal error no GeoAPIS service found !”);

response.setContentType(“application/json”);       String latitude = req.getParameter(“latitude”);
String longitude = req.getParameter(“longitude”);

// This initializes the authentication mechanism
LIServiceManager liServiceManager = LIServiceManager.getInstance(apiKey, apiSecret);
GeoEnhanceServiceImpl geoEnhanceService = liServiceManager.getGeoEnhanceService();

try {
Locations geoEnhanceResponse = geoEnhanceService.getPOI(Double.parseDouble(latitude), Double.parseDouble(latitude), null, 1, 1, “Miles”, null, null);
Gson gson = new Gson();
} catch (SdkException exception) {
if (exception.getErrorResponseType() == SdkException.ErrorResponseType.LI) {
ErrorInfo liApiErrors = exception.getLiApiErrors();

Now that your code is complete, you can deploy your .war file in the terminal with cf push. For example:

cf push LocationIntelligenceApp -p target/JavaApp.war

Once your application is deployed (which should take about 30 seconds), you can see the response message produced by the POI response back from the servlet with latitude & longitude values (https://< Application Name ><value>&longitude=<value>).

Congratulations! You’ve completed the step-by-step instructions. You now have a Bluemix app with location intelligence functionality provided by APIs from Pitney Bowes.

Special thanks to Kapil Dhawan for his contributions on the technical elements of this article.

More How-tos stories
April 5, 2019

IBM Cloud App ID: Updated Runtime APIs Provide Tighter Interoperability for Your Cloud-Native Apps

As part of our efforts to tighten interoperability and broaden the frameworks that are able to use IBM Cloud App ID, we've updated the runtime APIs.

Continue reading

February 11, 2019

IBM Cloud Mobile Foundation: Top-10 Features to Boost Your App Rating

The Mobile Foundation service offers many hidden gems that developers often gloss over. In this post, we highlight the top 10 features that increase user engagement as well as improve app ratings. 

Continue reading

February 8, 2019

Distribute CoreML Models Securely Using Mobile Foundation Service

IBM Mobile Foundation is excited to introduce a feature to manage the distribution of CoreML models.

Continue reading