This Data Transformation step utilizes the OpenCage forward geocoding API to extract longitude/latitude coordinates from a single text address column, or a combination of multiple address part fields, and then convert them into a GeoPoint value.

For more information on the OpenCage API: https://geocoder.opencagedata.com/ 

Set Up

In order to use this step, you must install the OpenCage 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.


It is worth noting that this step works with the Yellowfin 7.4 version that was released February 13th, 2018 or later.


Configuration Overview

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

Input Options




Step Output

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 wish to convert to geopoints. Our example shows address values stored in different fields.

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

  5. Connect the previous step to this one. 

  6. Click on this step to bring up its configuration details in the Transformation Flow panel. (Click here if you would like an overview of some of the step configuration details.)

  7. You have two options to configure the address, as discussed below:

    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 various address values for their corresponding fields.

  8. Enter the OpenCage API key. Yellowfin will save this key as an encrypted value.

  9. Enter a limit to control the number of times the key will be used when executing the flow in the preview mode. This will control the number of rows that are processed, since one request is used for each row.

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

  11. Once successful, the step will generate a new column called LongLat, displaying the converted geopoints. 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 the result by using an output step.




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