Build a simple photo location application with Pitney Bowes location services


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

Run the appGet the code

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.

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
    Screenshot of the two entitlement choices for the Pitney Bowes location-based APIs

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.

   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):

      <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.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

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