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
- A Bluemix account
- A Pitney Bowes developer account (see Step 1 for details)
- An Instagram developer account
- The CloudFoundry V6 command-line interface for your system
“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
- 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.
- 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.)
- 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:
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
- Log in to Bluemix.
- From the catalog, choose the Pitney Bowes geocoding service:
- 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 https://hub.jazz.net/git/jstart/Picture.Finder.(Node)
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.
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):
Step 4. Push the app to Bluemix
- Change to the app directory for the application. Log in to Bluemix
from the command line with:
cf login -a api.mybluemix.net
Supply your username, password, organization, and space when prompted.
- 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 (http://picturefinder.mybluemix.net/).
--- applications: #Reference http://docs.cloudfoundry.com/docs/using/deploying-apps/manifest.html - 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 mybluemix.net. Change. path: . #Path to the application to be pushed command: node app.js #The command to use to start the application services: - Geocoding-demo #the already created geocode service
- From the app directory that contains app.js and the manifest.yml file,
push your application:
When the application is running, go to http://my-unique-hostname.mybluemix.net (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.