Build a simple photo location application with Pitney Bowes location services

26 June 2014
PDF (235 KB)
Photo of Jay Allen

Jay Allen

Software Developer, Software Group, Strategy, jStart Emerging Technologies


Rachel Reinitz

IBM Distinguished Engineer; CTO, IBM Bluemix Garage


Srikant Varadarajan

Fellow, Integration Architect, Pitney Bowes


Robert Vila

Program Director and Senior Technical Staff Member, IBM WebSphere Strategy


Sign up for IBM Bluemix
This cloud platform is stocked with free services, runtimes, and infrastructure to help you quickly build and deploy your next mobile or web application.

IBM Bluemix™ features all the platform capabilities you need to build your great idea into an app or service. Bluemix also gives you access to a wide range of APIs that you can use to enhance your applications by mashing them up with capabilities provided by third parties.

Pitney Bowes provides powerful APIs for geocoding, address lookup, and more. Using a simple and fun example — an app that combines the latitude and longitude of any U.S. street address with a media search in Instagram — we'll show you how to use the Pitney Bowes APIs in your Bluemix applications.

What you need to get started


Bluemix gives you access to a wide range of APIs that you can use to enhance your applications by mashing them up with capabilities provided by third parties.

Quick tour of the Pitney Bowes location-based services


Four Pitney Bowes location-based services are available to developers using the Bluemix platform:

  • Geocoding— Converts addresses into geographic latitude and longitude locations.
  • Reverse geocoding— Converts a latitude and longitude location (such as a GPS signal) to a readable address.
  • Validate address— Corrects, standardizes, and validates addresses, ensuring that the address data adheres to quality standards established by the postal authority to improve the deliverability of mail and packages.
  • Travel boundary service— Determines boundaries around a location based on constant driving distance or constant driving time to increase confidence in geo-informed decision-making.

WATCH:See IBM Bluemix in action

READ:Pitney Bowes location-based services API documentation

Step 1. Register for the Pitney Bowes services

  1. Register for a developer account at the Pitney Bowes developer portal. When you complete the email verification step, you get an account with API privileges.
  2. Log in and register an application. The application ID that's returned is required to make API calls to Pitney Bowes. (The secret that's also provided is not currently required by the Pitney Bowes APIs.)
  3. By default, you have no entitlement to make API calls. On the Entitlements page, click Select Entitlement and select the free level (2,000 calls per day), which is automatically approved: Screenshot of the two entitlement choices for the Pitney Bowes location-based APIs

    Click to see larger image

Now you're ready to use the application ID with the Pitney Bowes services in Bluemix.

Step 2. Create a Pitney Bowes service instance in Bluemix

  1. Log in to Bluemix.
  2. From the catalog, choose the Pitney Bowes geocoding service: Screenshot of the Pitney Bowes geocoding entry in the Bluemix catalog
  3. Choose Do not associate. (You'll add the service instance to the application in Step 3.) Choose a name for the service instance and enter your Pitney Bowes application ID.

Step 3. Clone the Node.js picture-finder application code


Clone the Node picture finder application from the IBM jStart DevOps repository:

git clone

All the application logic is in app.js, which includes some Node modules that ease web application development:

  • The Express web development framework
  • The Hogan templating engine for Express
  • A REST client for calling Pitney Bowes
  • An Instagram API wrapper library
  • moment for date formatting
  • pinch for JSON manipulation

The post to /location makes a GET call to the Pitney Bowes geocoding service. Then the returned latitude and longitude are passed to Instagram (remember to replace instagramID and instagramSecret in the code with your Instagram developer account ID and secret) to retrieve JSON that describes all the pictures within a kilometer of the specified address.

Notice that the Pitney Bowes URL and application ID pulled from the geocoding service credentials are used in the call to the geocoding service.

Click to see code listing

   var Client = rest.Client;
   client = new Client();
   if (!address && !city && !state)

   // direct way
   client.get(url + "?address=" + address + "&city=" + city + "&stateProvince=" + state +    "&country=USA&fallbackToPostal=Y&fallbackToStreet=Y&fallbackToGeographic=Y&closeMatchesOnly=Y&appId   =" + appId, function(data, response){
               // data in callback contains the json returned from pitney bowes
            if (data.httpCode != "500")
               lat = data.Output.Geometry.Pos.Y;
               lng = data.Output.Geometry.Pos.X;
              lat: lat,
              lng: lng,
              complete: function(data){
               // pinch converts all unix timestamps to a friendly date
               pinch(data, /created_time/, function(path, key, value) {
                 return moment(value*1000).format("MMMM Do YYYY, h:mm a");

                res.render('index.html', {data: data, address: address, city: city, state: state});

              }, // end complete
            });// end search
            }// end httpCode check
              msg = "Can't find any pictures near this address";
              res.render('index.html', {msg: msg, address: address, city: city, state: state});

           }); // end PB call

Hogan and the ultra-clean mustache templating language display the results in the index.html view. It renders straight from the JSON returned from Instagram (with the created time changed, using the pinch library on the server side, from a UNIX timestamp to a friendly date format):

Click to see code listing

      <li style="display: inline-block; padding: 25px"><a href="{{link}}"><img src="{{#images}}{{#thumbnail}} {{url}} {{/thumbnail}}{{/images}}"></a> <br/>
         By: <em> {{#user}} {{username}} {{/user}}</em> <br/>
            {{#comments}} {{count}} {{/comments}} comment(s)  {{#likes}} {{count}} {{/likes}} likes. </li>   

Step 4. Push the app to Bluemix

  1. Change to the app directory for the application. Log in to Bluemix from the command line with:
    cf login -a

    Supply your username, password, organization, and space when prompted.
  2. A manifest.yml file is included with the application to streamline the process. It sets the application name, memory, number of instances, and the Pitney Bowes geocoding service name you created in Step 2.

    Edit manifest.yml to change the values that must be unique for your app. The host name must be something other than picturefinder so that your resulting URL route doesn't conflict with the demo URL (

    applications: #Reference
    - name: PictureFinder #Application Name. Unique to the user's Space
      memory: 256M #The maximum memory to allocate to each application instance
      instances: 1 #The number of instances of the application to start
      host: my-unique-ehostname #Hostname for app routing. Unique to domain  Change.
      path: . #Path to the application to be pushed
      command: node app.js #The command to use to start the application
    - Geocoding-demo #the already created geocode service
  3. From the app directory that contains app.js and the manifest.yml file, push your application:
    cf push

When the application is running, go to (where my-unique-hostname is the host name you used in the manifest file). Enter your address and see what Instagram users are posting near you.



More than 1.2 billion people worldwide use Pitney Bowes location intelligence solutions when they check into or use location-sharing features on major social media platforms. These same services can help make your apps more engaging by tailoring users' experiences to their current location.

Add a comment

Note: HTML elements are not supported within comments.

1000 characters left

developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Zone=Cloud computing, Web development
ArticleTitle=Build a simple photo location application with Pitney Bowes location services