Understanding reverse geocoding in Survey123 3.0

07-05-2018 07:03 PM
Occasional Contributor
7 33 15.6K

Survey123 version 3.0 has introduced both geosearching and reverse geocoding functionalities, to allow users to both search for street addresses and places of interest when capturing a location, as well as to retrieve the location of a point already selected. Making full use of reverse geocoding can be difficult, though, and we wanted to make sure people could make the fullest use of it right out the gate. So this blog post will describe everything about the new reverse geocoding functionality that we can, so that you can hit the ground running with it!


Reverse geocoding can be performed in the field app by pressing and holding on the map or coordinates when the full geopoint view is opened, but this is only for confirming the location when it’s being captured; the full geocoded description of the location isn’t saved and submitted to the survey. However, the reverse geocoded value can be obtained from the geopoint and inserted into a field in your survey using pulldata("@geopoint",${location},"reversegeocode"), which returns the location as a JSON object that looks something like the following:


               "Match_addr":"570 St Kilda Rd, Melbourne, Victoria, 3004",
               "LongLabel":"570 St Kilda Rd, Melbourne, Victoria, 3004, AUS",
               "ShortLabel":"570 St Kilda Rd",
               "Address":"570 St Kilda Rd",        "Block":"",


Please note that this blog post uses the ArcGIS World Geocoder for our examples, so be aware that other locators won’t produce exactly the same contents. Also know that, when using these reverse geocoding expressions, ArcGIS credits will be consumed if you're using the ArcGIS World Geocoder.


Individual properties from the object can be extracted by providing the name of the property alongside reversegeocode, separated by periods. These properties themselves differ depending on the locator used, but the format always remains the same. This example would return only the “Match_addr” property seen in the JSON object above.




The default locator service for your organization will be used when reverse geocoding. To use a different locator service, enter the locator URL as an optional parameter into the function with the format pulldata("@geopoint",${location},"reversegeocode",${locatorURL}). If the service is secured, a proxy item must be configured with access credentials saved in it. For more information, see Requirements for configuring your own locators for ArcGIS Online, or Configure utility services with your portal for ArcGIS Enterprise.


If a locator URL is provided, additional parameters can be provided that will be passed to the URL. As with the properties provided within the JSON object, these parameters differ depending on the locator service used. This example uses the featureTypes parameter, which limits the value returned to a specific type of location, to return only the nearest business or landmark.


pulldata("@geopoint",${location},"reversegeocode.address.Match_addr","https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer","featureTypes=" + "POI")


Usually, the ArcGIS World Geocoder has two required parameters that you also need to pass through the URL: location and token. These are provided automatically by Survey123, however; you don’t need to do anything about these.


There’s a few other useful parameters you can use with the ArcGIS World Geocoder:


  • langCode can be used to set the language reverse-geocoded addresses are returned in, for countries that have multiple languages available. Remember to define only a two-digit locale code, rather than a full language name.
  • locationType specifies whether PointAddress geometry is placed on the rooftop or street entrance of the location. If this parameter isn’t provided, it defaults to street.
  • forStorage is automatically passed to the geocoder by the Survey123 app, and is used to allow the result to persist. While usually an optional parameter, in the case of Survey123 it’s treated in the same way as compulsory parameters.


For more information on reverse geocoding URL parameters, including a full list of parameters that can be passed to the URL, see the ArcGIS REST API's documentation on the reverseGeocode operation.


You can include multiple reverse geocoding calculations without an impact on performance or credits. As an example, these three calls for individual properties could all be included:






A reverse geocode will be performed for the first calculation, which would consume credits. After this, the response is cached, and used for the other two calculations. A new call to the geoservice is only required if the reverse geocode request URL has changed, either due to a change in location, using a different request parameter, or the original access token expiring.


Hopefully, this blog helps you implement reverse geocoding into your own surveys. If you have any other questions or issues about reverse geocoding, feel free to leave them in the comments below, or bring them to the Survey123 booth at the UC!

New Contributor III

Thanks! This is really helpful. How would you pull out just the state abbreviation for a US State?

Regular Contributor II

Thank you for your quick response.



Occasional Contributor

The reverse geocode doesn't appear to work when using the browser interface.  Is that something that's on the roadmap to fix?

Occasional Contributor

Yes, reverse geocoding isn't yet supported by the Survey123 web app. This is being worked on, but I'm not certain when it will be implemented.

New Contributor II

I get valid coordinate data when using pulldata("@geopoint",${location},"x"), but my field remains blank when I try pulldata("@geopoint",${location},"reversegeocode.address.ShortLabel").  Even when I get an address on the geolocate map screen.

Using Survey123 Connect, publishing to an existing feature layer on my Enterprise Portal (which I am signed into).

Esri Esteemed Contributor

Hi Becky,

The specific statement to look for will vary from geocode to geocode - you may need to examine a sample result (like the one shown at the beginning of the blog) to identify the correct keyword sequence.

New Contributor II


How do I get it to print the JSON so I can see what statement I need to use?

Esri Esteemed Contributor

Hi Becky,

The easiest way would be to go to the REST URL of the locator service (ends in /GeocodeServer) and navigate through findAddressCandidates and attempt a sample geocode; you can specify JSON as the output. 

Esri Contributor

Hi, I'm just trying to implement this but I'm getting the following error when I use the following calculation: pulldata("@geopoint",${geopoint},"reversegeocode")

{"error":{"code":499,"extendedCode":-2147220966,"message":"Token required but not passed in the request.","details":["Token required."]}}

In the post mentioned that there is nothing to do about the token parameter, is there something wrong that I'm doing?


Esri Esteemed Contributor

Hi Javier,

Are you logged in? The World Geocoder (which charges credits for reverse geocodes) requires you to be logged in.

Esri Regular Contributor

Hi Javier

If you sign into a portal that uses the default geocode service configuration (i.e the inbuilt Esri World Geocoder item is at the top of the list in the portal settings) - you will get an error when trying to perform a reverse geocode using pulldata("@GeoPoint",${location},"reversegeocode") if you do not specify a URL parameter. This is because the app will use the first locator service in the portal list and if it is the default World Geocoder it will require a token (even though the service is public).

To get this working the user must create a proxy item in the portal and put this at the top of the locator list. See: https://docdev.arcgis.com/en/survey123/desktop/create-surveys/geopoints.htm#ESRI_SECTION1_E89036D9C3... 


  • Create an item in the portal org that links to the url for the world gecocode service (https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer) and has AGOL credentials saved into it. The credentials must be for an AGOL org user that has the permissions to perform geocodes (Geocoding).
  • Create a new locator in the portal based on the service URL of the item created above and add it the top of the locator list.
  • This will now be the default geocode service for the portal and will work for reverse geocodes (where a url paramter is not specified in the function).



New Contributor II

This might be asking a bit much from this functionality, and I just want to say that your team's support & development of it has been awesome - I was wondering if there was a way to have a text field with an address populate the locator box in the geopoint question. It's not a huge workflow issue if not, it's just that with several web-based browsers on mobile devices the geopoint question can be a little cumbersome to find the locator box, and we are planning on using survey123 to collect address information of event participants, so want their exit form process to be simple & quick. If they could just enter the address in one box and have the locator find it automatically it would shorten some of the confusion & generational technology gaps we experience at events. 

Esri Esteemed Contributor

Hi Savannah,

Thanks for the idea!  This currently isn't possible in Survey123, though I've recorded this as an enhancement to consider in the future.

Esri Contributor

Hi James Tedrick‌ and Claire Proctor‌,

any new update here? It seems that the reverse geocoding is still not working in the Survey123 web app.



Esri Esteemed Contributor

Hi Sven,

Reverse geocoding should be working in the web form now.  Note that you will need to either republish the survey or turn off version locking in the settings to see the update (see Web app version—Survey123 for ArcGIS | ArcGIS )

Occasional Contributor

Hi Becky,

Were you able to navigate through the findAddressCandidates to get a sample geocode? I am having the same issue as you where the pull data gets the X and Y but not the street address. I don't know how to get the sample JSON to view the correct statement. 

New Contributor II

No, I was never able to get it to work. I have now moved on to another position, and don’t have access to a system to play with it any more.

Esri Esteemed Contributor

Hi Molly,

Are you able to look at the geocoding results in a web browser?  That is probably the quickest way to determine how to get the fields you need.

Occasional Contributor

Hi James,

I'm not sure how to view the results in a web browser. I don't get any results when I use the pulldata - reverse geocode function in my survey. I'm trying to follow the blog post by using the ArcGIS online world geocoder. I don't get an error message when I publish the survey. Yet, when I fill out the survey, the reverse geocode yields no results and the address field is blank. I've tested it in both the Survey123 app on my phone and computer and a web app on my computer.

Occasional Contributor

I was able to figure it out. I was including the ArcGIS online world geocoder URL in the statement. I removed the URL and now my calculation works:

pulldata("@geopoint", ${Last_Location_Geo}, "reversegeocode.address.Match_addr")

New Contributor

Hi James, same issue here. I succeed at querying Match_addr, but all other fields fail (AddNum, ShortLabel, etc). I went into the Locator and queried an address in the Find Address Candidates as JSON to try and output a sample result, but it doesn't return the field names with related address parts like in the sample above. It only outputs the wkid and LatestWkid.

Esri Esteemed Contributor

Hi Andrew,

It sounds like this might be an issue with the geocoder - which one is being used?  Could you provide examples of the query you are passing to it?

New Contributor III

Is there a diffrence in using the newer ArcGIS Pro built Locator styles? I created a new locator with Pro and published to our Portal but cant seem to get a response in Survey123 Connect. I have tested the JSON from the service and can get a result back.

{ "address": { "Match_addr": ....

The calculation in the XLS form

pulldata("@geopoint",${location},"reversegeocode.address","GeocodeServe SERVICE URL")

Esri Esteemed Contributor

Hi Glen,

To my knowledge there isn't a change in the REST response between geocode services. Just to check, have you tried to load just the reversegeocode object?

Occasional Contributor II

Is it possible to configure Survey123 to work offline with a custom geocoder?

Esri Esteemed Contributor

Hi Josh,

At this time, Survey123 cannot use an locator package (offline geocoding).

New Contributor II

I have a similar issue as some above. I am trying to basically duplicate a record. I need to be able to add records to a survey as a new survey to create a history of incidents at a location. Right now, I create a new survey and copy all the data from an existing surveys fields using the GlobalID. I can achieve what I am after if I select an address from my choice list, however, when I don't have an address and use the reverse geocode option, when I go to repeat the same process as above it does not go back to the location I placed the pin at. How do I get the new survey to go to the location where I dropped the pin at in the existing survey? I used pulldata("@geopoint", ${location}, "reversegeocode.address.Match_addr") but it drops a pin at my default location where the map is centered on. Ideas?

begin groupaddress_selectSelect Address      
select_one addressaddressSelect Address from ListIf not in list select "Other"autocomplete    
select_one YesNoIndicatorAddressInListAddress <i>Not</i>Listed? (Y / N) minimalYesif(selected(${address},'+029.9445_-90.3728'),'No', 'Yes')esriFieldTypeString50
geopointlocationAddress LocationIf no address center map on pin by dragging maphide-input concat(substr(${address}, 0, 9)," ",substr(${address}, -8))esriFieldTypePointZ 
end groupaddress_selectend       
begin grouplocation_selectSelect Location on Map Above minimal    
select_one yes_noconfirm_reversegeocodeRun geocode services minimalNo   
hiddenreversegeocode_json_outputJSON Results multiline pulldata("@geopoint",${location},"reversegeocode","","featureTypes=" + ${featuretypes})esriFieldTypeString4000
select_one featureTypesfeaturetypesSelect output type (Address or Street Intersection)   <i>If other than street address</i>minimalPointAddress esriFieldTypeString50
textaddresEnter Address Not in List   pulldata("@json",${reversegeocode_json_output},"address.Address")esriFieldTypeString50
end grouplocationgroupendend group      
New Contributor II

Hi Greg. Did they answer your question about this? I'm trying to do the same thing with pulling out only the street name, and I can't get it to work. 

Esri Contributor

Hi James,

are there any plans to support custom locators that are a part of a mobile map package with Survey123? The pulldata feature works really well, but I need it to work offline.



New Contributor III



I am not able to get the reverse geocoding working for web app either. I have republished the survey and also checked the Always use the latest version (3.11) option? What am I missing? Did anyone get this to work on web app? Please let me know.

New Contributor III

@msa4012 I ran into the same issue, and found the article linked below. Basically if the service is secured or the survey is public you need to configure a proxy item in AGOL with access credentials. I have not tried doing so yet, so I don't know if that will solve your issue but at least it's somewhere to start. 

https://doc.arcgis.com/en/survey123/desktop/create-surveys/geopoints.htm Scroll down to the reverse geocoding section of the article and there is more information on configuring the proxy item in AGOL.

Good luck!

New Contributor III

Can you clarify if we were to use our internal Geocoding service if this will still use credits? 

New Contributor

Hi Vanessa!

If the service does not use the ArcGIS World Geocoding Service, it should not use any credits.  Using your own should not cost any credits.

Thank you very much!