Overview

Users can utilize the PitneyBowes forward geocoding API to extract longitude and latitude coordinates from the input of an address, and then convert them into a GeoPoint value. This is ideal for enhancing customer addresses.

Set Up

In order to use this step, you must install the PitneyBowes Geocode plug-in in your Yellowfin environment.

1. Download the plug-in from the Yellowfin Marketplace. (You can find it under the Transform Steps panel.)

2. Install it on your instance of Yellowfin. Click here to learn how to do this.

Step Configuration Overview

These details will enable you to configure this step with ease.

Input Options

• Basic configuration: In this mode, the entire address is provided as a single line input. 

• Advanced configuration: In this mode, individual elements of an address are specified separately. Any fields that are left blank, or values that are null will be ignored. As this is more specific it will tend to produce better results than the full address version.
  
  

  You can also concatenate a split up address in separate fields together by using the Calculated Field step, and stringing each field with a plus (+) operator.

  
  
  

• API Key and API Secret: These are your credentials to the PitneyBowes API. These values are necessary to run the geocoding step. To obtain an API key see: https://www.pitneybowes.com/us/developer/geocoding-apis.html 
• Preview Mode Row Limit: The PitneyBowes API uses a system of credits that can be quickly consumed when configuring and testing a transformation flow. You can use this field to set a safety limit on the amount of credits that will be consumed by this step in a preview run. If this value is set to 0, then no limit will be applied. The number you specify here will affect the number of rows in the data preview panel, as each data row uses a credit. Note, however, that this safety limit will not be enforced when the flow is published and run.

The API will return a list of possible longitude/latitude coordinates, based on the level of detail provided for an address. This step will select the primary match from this list. If the API does not return any matches (which could happen if insufficient address details were provided), then a null value will be displayed.

The point returned will be a centroid for the level of match the API was able to make. For example, if a street address is provided and the API was able to match this to a real street address, the geopoint will be located at that exact address. However, if only the city was able to be matched, then the geopoint returned will be at a central location for that city.

As not all databases can store geometry field types, the matched geopoint will be returned as a POINT(Long,Lat) text string, for example: POINT(-112.1234, 45.123). This value can then be converted to geometry objects for map display using database functions (such as SQLServer) or Yellowfin’s view-level Well Known Text or WKT converter.

Step Instructions

1. Navigate to the data transformation module. (Create button > Transformation Flow)

2. Access the input steps list and use a step to import data into the flow.
   
    
   
   

3. Ensure that your data contains address values that you want to convert to geopoints. Our example shows address values stored in different fields.
   
   
   
   

4. Once you are ready to use the PitneyBowes Forward GeoCode step, open the transformation steps panel, and drag the step into your flow. 
   
   
   
   

5. Then connect the previous step to it. 
   
   
   
   

6. Click on this step to bring up its configurable details in the Transformation Flow panel. (Click here if you would like to see a detailed overview of these settings.) 
   
   
   
   

7. You have two options to configure the address:

1. Basic configuration: Through this default mode, you can include a full address contained in a single field. Choose this field from the Full Address dropdown. 
   
   
   
   

2. Advanced configuration: If your address is divided amongst various fields, then use this mode:
   
   
   
   

1. Enable the Advanced Configuration toggle. This will reveal additional setting options. 

2. Select the different address details. 

8. Enter your PitneyBowes API key and secret. Ensure that your API key has limits available for this step to work.
   Note: Yellowfin will encrypt this values when saving them, so they are always secure.
   

9. Set a limit to the number of times you can use the API credentials in the preview/test mode. This is to ensure that you do not exhaust your API credits while testing the step in the preview mode. The limit you define here will not influence the actual tries during a full or scheduled execution (i.e. when not in the preview mode).

10. Once you have provided all the configuration details, click Apply. 
    
    
    
    

11. If successful, the step will display the converted geopoints in a new column called LongLat in the data preview panel.
    Note: This is the default column name of this output. You can always rename it. 
    
    
    
    

12. You can continue transforming your data by adding more steps, or save this result by using an output step.

Troubleshoot

If your step has failed, it could be for a number of reasons:

• Your API key limit has been exhausted. You will need a new key to continue using this step. 

• An incorrect API key was provided.

• The input address fields you provided are incorrect (or do not match the column data type).