Location Data Knowledge Base

Data methodologies, and Release schedules.

Tool Mastery | Reverse Geocoding Macro


Reverse Geocoder.png

This article is part of the Tool Mastery Series, a compilation of Knowledge Base contributions to introduce diverse working examples for Designer Tools. Here we’ll delve into uses of the Reverse Geocoding Macro on our way to mastering the Alteryx Designer:

Have some Latitude/Longitude points and not much else? Working with Spatial Objects and need more information than a simple map point? Time to call in the Reverse Geocoding macro. Reverse Geocoding can give some robust information to help make important business decisions when working with spatial data. Case in point: Your “friend” has hacked the Pokémon Go APK and hands you a list of Pokémon with the associated Latitude/Longitude. You can’t make an informed decision on your next weekend Poke-session without first understanding more than just the location on a map!

This macro queries the TomTom Reverse Geocoding API to produce a record-for-record reverse geocode result. In addition, a summary output is produced that provides a count of records that were successfully and unsuccessfully reverse geocoded. We have had multiple requests from you all for a reverse geocoder, and while we have some great articles outlining a more manual process (see Approximate Reverse Geocoding Information from Latitude and Longitude Coordinate Pairsand Worldwide Reverse Geocoding in Alteryx?), Alteryx is about making things simpler! We do our best to avoid having “Alteryx” and “manual process” in the same sentence.


  • This tool requires internet access, as it is querying TomTom's Reverse Geocoding API.
  • This is a macro that is installed with a separate data install found on the SpatialData Bundle installation Disk. If you do not see this tool in the Tool Palette and are interested, contact your Customer Support Engineer at support@alteryx.com.
  • This macro is available for all countries where we provide Spatial Data.
  • For those of you with strict firewalls or proxy, have your IT department whitelist traffic.tomtom.com to avoid errors such as:

Tool #13: Error transferring data: Failure when receiving data from the peer.

  • The Reverse Geocoder will error if there are special characters - nulls, \ and ", etc. It's always a good idea to cleanse your data before any kind of manipulation, but it's especially important here - you'd hate to be 80% through an 8 hour workflow, only to error on random special characters!


The User can select either a single Latitude/Longitude field, multiple fields, or a Spatial Object field for input.


The User can decide which output fields to keep and whether to keep incoming fields (listed under Additional Options).



Geocoded Output (G): The record-by-record reverse geocoded results.

Summary Output (S): Provides a count of records successful and unsuccessfully reverse geocoded.


  • The performance of the tool is also related to network speed; this includes the travel distance and speed of the request to TomTom’s servers, and the amount of traffic on that service. This can also be affected by the processing logic TomTom uses to identify which records to fetch coordinates from, and the response time to/from the “logic layer” and their data store.
  • You can also cache or store the intermediate results, in case something errors downstream.


According to TomTom, “Most often this is needed in tracking applications where you receive a GPS feed from the device or asset and wish to know what address where the point is located.” As we know that Alteryx users come from many different industries and departments, this is just one of the many uses. Here are a couple ideas to help get you started:

  • Deconstructing Lat/Lon into Address points for CASS validation prior to shipping to locations
  • Data investigation of a Spatial file to get information such as Country, ZIP or Municipality

By now, you should have expert-level proficiency with the Reverse Geocoding Macro! If you can think of a use case we left out, feel free to use the comments section below! Consider yourself a Tool Master already? Let us know at community@alteryx.com if you’d like your creative tool uses to be featured in the Tool Mastery Series.

Stay tuned with our latest posts every Tool Tuesdayby following Alteryxon Twitter! If you want to master all the Designer tools, consider subscribingfor email notifications.

5 - Atom

Hey Sophia,


I know this thread is two years old but I'm getting an error when I run this example (or any other reverse geocoding workflow).


"Invalid value. at character position: 0."



I didn't change anything with the original example and considering this seems to work for everyone else, I'm a bit stumped. Any ideas?




8 - Asteroid

I am having the same Issue as Lenny above.

5 - Atom



I'm experiencing the same issue as well - exact same error. Were you ever able to find a solution?

5 - Atom

I'm experiencing the same issue too, regardless if I read in lat/lon pair, lat/lon as separate fields, or lat/lon converted to spatial object centroids. Does anyone know what's causing the problem?

5 - Atom

I also see the same issue. Is it a data set behind the reverse geocoder tool being out of date?  It fails for all attempts of lat/lng.

7 - Meteor

I'm getting the same error listed by many others above.  Has there been a solution/update for this?  I was getting this when I set it up with my own data.  I found this post and downloaded this module and ran it, same error.  




The issue here is either a lack of internet access or strict firewalls or proxy. 


Internet access is needed for the Reverse Geocoding Macro to query TomTom's Reverse Geocoding API.  Additionally, the issue could be the result of strict firewalls or proxy and your IT department needs to whitelist traffic.tomtom.com. 


Tool #294 in Reverse Geocoding Macro is a JSON Parse tool that is supplied input from TomTom's Reverse Geocoding API.  It seems that the API call that connects to the JSON Parse tool is providing an error message instead of the expected data.  The JSON Parse tool is unable to interpret the input its given and throws the error for an "Invalid value. at character position: 0".


I just ran this workflow and identified that it is running correctly:




5 - Atom

Hi Mweik! We are facing this error "Invalid value. at character position: 0.".

You mentioned that we need to get whitelisted traffic.tomtom.com but we don’t know the specifics i.e. Port(s), Protocols, destination, etc…

Can you provide the details?