Survey123 Tricks of the Trade: A built-in compass for your forms

11-29-2021 05:25 PM
Esri Notable Contributor
7 8 1,275



There are some specific field data collection workflows where you may want to capture the direction of things. Geologists, for example, measure the horizontal orientation, or strike, of geological faults. During an inspection or hazard assessment, you may need to report in what direction a utility pole, or tree, is leaning.

While you can always add a numeric question to your Survey123 form and ask field users to measure direction with an external compass, in this article I will describe how you can measure the direction of things using a built-in compass right within your Survey123 smart form.

This feature is not documented, other than through our Early Adopter Community website, so I thought I would bring some extra visibility to it.  Familiarity with XLSForm and Survey123 Connect is assumed.

The Survey123 compass control uses the magnetometer in your mobile device to measure the orientation of your device. All you need to do is to align your device with the direction you want to measure. Once you are happy, you tap on the compass control to lock the measurement.

The compass control also includes an indicator on the side. If your device magnetometer is not calibrated correctly, the pointer will move into the red zone.

To add the compass control into a smart form, add a decimal question and set its appearance to bearing. Please note that the bearing appearance is not documented, nor is it included with the Survey123 templates. You will need to type the word bearing into the appearance column manually.


The compass control returns the azimuth measured against magnetic north. If you want the azimuth measured against true north, you need to correct the measurement using the magnetic declination at your location.

If you plan to use your survey in a reduced geographic area, you can get the magnetic declination for your area from the NOAA website and use a calculation in your form to make the adjustment.

For example, for the city of Redlands, in California, the magnetic declination is 11.45 degrees. In my XLSForm, I add a new question to apply the correction. Note that I also set the bind::esri:fieldtype column to null in the question with the bearing appearance, because I do not want to store the value without the adjustment.


If you want to get fancy, you could dynamically calculate the magnetic declination based on your location using a custom JS function.  Here is one showing how this could be done. Note that the function makes a call to the NOAA Magnetic Declination online calculator service. This function will not work if you are offline. 



    function getMD(location){

		var coordsArray = location.split(" ");
     	var lat = coordsArray[0];
		var lon = coordsArray[1];

        var url = "" + lat + "&lon1=" + lon + "&resultFormat=json";

        var xmlhttp = new XMLHttpRequest();   "GET",url,false);

        if (xmlhttp.status!==200){
            return (xmlhttp.status);
        } else {
            var responseJSON=JSON.parse(xmlhttp.responseText)
            if (responseJSON.error){
                return (JSON.stringify(responseJSON.error));
            } else {
                return JSON.stringify(responseJSON.result[0].declination);



Here is the corresponding XLSForm:


Similarly, you could adjust the direction values using workflow automation with Integromat or Microsoft Power Automate. If you take that approach you could work offline and still have the true north azimuth values calculated dynamically. Ah! Of course, you can also use ArcGIS Pro or a Python script!

Again, I think that for most cases you may be fine calculating the magnetic declination for your area and hard-coding the value in the form logic, but other options exist for you to make corrections dynamically if you need to.

One last thing to keep in mind: the bearing appearance is only supported in the Survey123 field app.



Occasional Contributor

I like this visual functionality.  It appears that there will be a need to have the user "refresh" the compass calibration prior to using the form each day. Is there possibly a time limit in which the device/app would retain the calibration? No worries either way and I think it would rather amusing to watch the field crews completing figure eights each morning.

Occasional Contributor III

Nice! Any chance of also capturing the dip, in addition to the strike?

New Contributor II

Well that's cool. Have to play around with it with our field surveys. Thanks for the update.

Esri Notable Contributor

@MichaelBruening  In my own experience, there is no need to re-calibrate the compass prior to using the form each day.  There is a possibility that in some old Android and Apple devices you may need to calibrate more often. 

The Survey123 app cannot do anything to re-calibrate the compass. The indicator on the side simply tells you if you need to re-calibrate or not. In the end, the calibration and accuracy of the compass relies completely on the sensors in your device.

Esri Notable Contributor

@PeterKnoop  For measuring the dip, please consider describing your use case and voting up this idea

Occasional Contributor

@IsmaelChivite understood on the device's sensor controlling the accuracy of the compass. I will add a note into these questions to check the calibration of the compass with the indicator to the right of the compass.

Occasional Contributor III

I am curious how or if this takes into account the orientation of the device - portrait vs landscape.

This may be a totally different scenario from this new appearance, however I am curious because we had done testing a few years ago in regards to the internal device compass direction that is captured in a photo's EXIF data.

What we found was that if we wanted users to take landscape-oriented photos, they needed to be consistent about how they did this. We instruct users to always take landscape oriented photos with the "home button" (bottom of device) in their right hand. Then, we were able to accurately calculate the compass direction within a report template based on that known orientation of the device at the time of capturing the photo. 

Would a similar sort of calculation need to take place within the survey form for this type of question depending on how users are holding their device when completing their survey?

We use this calculation within a report template to determine the actual compass direction that the photo is facing from photo EXIF data. Again, maybe this is different because it is relating to a photo/EXIF data/report templates, but I thought this was worth asking. 

${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=0.0) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=22.4))} E ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=22.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=67.4))} SE ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=67.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=112.4))} S ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=112.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=157.4))} SW ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=157.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=202.4))} W ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=202.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=247.4))} NW ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=247.5) && ((Image | getValue:“direction”)<=292.4))} N ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=292.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=337.4))} NE ${/}${if (((Related_Table_Photo_Information.Image | getValue:“direction”)>=337.5) && ((Related_Table_Photo_Information.Image | getValue:“direction”)<=360.0))} E ${/}

Esri Notable Contributor

@erica_tefft   The compass appearance is of little use for your workflow. In your case, it looks like you want to get the direction of the photo. Using the EXIF info is the best approach.