Customizing the geocoders shown in Map Journal, Map Series, and Shortlist

The March 2017 release of Story Maps on ArcGIS Online includes additions and upgrades to map search in Map Series, Map Journal, and Shortlist. Authors can now make available to readers the geocoders that are configured by an administrator in their organization’s Utility Service.

Geocoders configured in your organization (left) can now be made accessible to your story map readers (right).

There isn’t a way in these story map builders for authors to choose which geocoders are shown to readers; however, the list of geocoders is stored in the story configuration JSON, so (yep, you guessed it…) you can use the ArcGIS Online Assistant to edit the JSON to make changes to this list.

WARNING — Editing JSON can break your story!

If you’ve never edited story map JSON before it’s wise to first try it a few times on a test story until you’re comfortable with the procedure. If you choose to edit JSON for a published story, be aware of the risk you are taking and be sure to copy and save its original JSON in a text file in case something goes wrong.

Here’s an example of the JSON that stores the geocoders for your story:

"appGeocoders": [
        {
          "singleLineFieldName": "SingleLine",
          "name": "San Diego Places",
          "placeholder": "Find a place in San Diego",
          "url": "https://server1.com/../GeocodeServer"
        },
        {
          "singleLineFieldName": "SingleLine",
          "name": "San Diego Parcels",
          "placeholder": "Find a parcel by PIN",
          "url": "https://server2.com/../GeocodeServer"
        },
        {
          "singleLineFieldName": "SingleLine",
          "name": "Esri World Geocoder",
          "url": "https://geocode.arcgis.com/.../GeocodeServer"
        }
      ],

By editing the JSON you can:

• Remove a geocoder. This is the most likely reason you’ll want to use the technique described in this article.
• Add a geocoder.
• Rearrange geocoders so they appear in a different order.
• Change the name and placeholder coming from your organization’s settings. You are not able to change these for the Esri World Geocoder.

To customize the geocoder list…

1. Open ArcGIS Online Assistant and log into your ArcGIS account.
2. At the top click I want to…View an item’s JSON.
3. In the left panel, find the story map you want to customize. These instructions are for Map Journal, Map Series, and Shortlist stories only.
4. In the Data section of the right panel, look for appGeocoders in the JSON (as shown above). As mentioned above in the warning, now is a good time to Copy the original JSON and save it in a text file in case something goes awry. If you don’t see appGeocoders, see the note at the end of this post.
5. Click Edit (the pencil button) to start editing the JSON.
6. Edit the appGeocoders as desired. Make sure to match brackets, etc. to keep valid JSON format.
7. Save your changes to the JSON using the Save button at the top of the Data section.
8. View your story or open it in builder (if it’s already open, reload the page) to view your changes to the geocoders.

What about private/secure geocoders?

Some geocoders you see in builder or that you add to the JSON may not be visible to all readers:

• Geocoders on your internal network will only work for colleagues on the same network; they will be visible to — but won’t work for — readers outside your firewall.
• Geocoders that require a login are not supported.

So, you may see some geocoders when building your story that won’t work for some of your readers. Be sure to be aware of the conditions above and test your story in an environment typical of how your audience will access it. We recommend using the technique described in this article to remove geocoders that won’t work for your readers.

Anything else?

• When possible, use HTTPS URLs for geocoders you add.
• If an administrator adds a geocoder to your organization after you’ve created your story, it won’t appear in your story. You can manually add the new geocoder to the JSON if you want it to be available to your readers.
• If you remove the Esri World Geocoder and want to add it back, use this URL:

https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer

• You may want to turn off search suggestions if your geocoder doesn’t support them or to simplify the search experience. Just use the enableSuggestions parameter:

"singleLineFieldName": "SingleLine",
"name": "what3words",
"placeholder": "find a 3-word address",
"enableSuggestions": false,
"url": "https://what3words.com/..."

What if you don’t see JSON for the geocoders?

If you don’t see appGeocoders in your story JSON settings, it’s likely because you haven’t opened your story in the builder since the March 2017 software update. Just open your story in builder mode, then refresh the JSON view in ArcGIS Online Assistant by clicking the item name in the left panel. This will write the geocoders to the JSON so you can edit them. Now you can proceed with the steps above.