Point Based Service access with ArcGIS Earth

In honor of the Esri Developers Summit going on right now in Palm Springs, California, I thought that I’d provide a quick look at a hidden capability in ArcGIS Earth 1.0 that allows a developer to enable end users to access additional information about a location.

Note: If you haven’t downloaded ArcGIS Earth, yet, get it here!

If you take a look at the Administer web pages in the ArcGIS Earth documentation, you can see an innocuous entry called ServiceURL that can be configured in the ArcGISEarth.exe.config file that is in the Earth install directory.  The secret to this parameter is that it allows an administrator to enter a URL with some encoded values that will be recognized by Earth and filled with location information.  When a user then uses CTRL-RIGHT-CLICK on the globe, the URL will be invoked and the latitude, longitude, and elevation of the point clicked will be passed to that URL.  As long as the URL returns valid KML, the KML will be displayed in the Earth viewport.

In doing some experimentation, I found that I could add a call to What3Words so that I can get the unique three word location for any spot on the planet.

In the same way, I could be able to call a Mapillary or HERE service as well.  In experimenting with this, I found some limitations to the Earth embedded browser that I need to further investigate, especially when calling apps with JavaScript.

What3Words doesn’t export KML. So how did this happen? It does require a little black magic.

These are the steps that I followed:

• 1. Set up a simple CherryPy server
• 2. Created a simple KML template file that I could call repeatedly and placed it somewhere that I can load it in python

<?xml version="1.0" encoding="UTF-8"?>
<kml  
     >
<Document>
<name>%title%</name>
<description><![CDATA[%description1%]]>
</description>
<Placemark>
 <name>%lon%,%lat%</name>
 <styleUrl>#golf-balloon-style</styleUrl>
 <description><![CDATA[<img 
     src="http://www.yakjive.com/styles/
     icons/spaceship-orange.png"/>]]>%descrip
     tion2%</description>
 <LookAt>
 <longitude>%lon%</longitude>
 <latitude>%lat%</latitude>
 <altitude>%elevation%</altitude>
 <heading>0.00265562742696041</heading>
 <tilt>0</tilt>
 <range>11030676.39798315</range>
 </LookAt>
 <Point>
 <coordinates>%lon%,%lat%,%elevation%</coordinates>
 </Point>
</Placemark>
</Document>
</kml>

• 3. Created cherrypy app with a method that would represent my call from Earth that would be used to invoke the desired service.  In the case of What3Words, this was a simple method that builds some HTML around the What3Words request and embeds it in a basic KML placemark.  The pseudocode method looks like this:

@cherrypy.expose
def callWhat3Words(self, lon=0, lat=0, elv=0):
  cherrypy.response.headers['Content-Type']= 'text/xml'
  w3wURL = 'https://api.what3words.com/position?key={MYKEYNOTYOURS}&position=' 
     + str(lat) + ',' + str(lon)
  req = urllib.request.Request(w3wURL)
  c = urllib.request.urlopen(req)
  res = c.read()
  data = json.loads(res.decode("utf-8"))
  #Build my HTML that will be embedded in KML
  description1 = 
    '<div height=250 width=400 style="font-family:Verdana;">' + 
    '<img src="http://127.0.0.1:8585/templates/what3words_logo.png"' + 
    ' height=139 width=400/>' + 
    '<p><span style="color:blue">' + 
     data['words'][0] + ':' + 
     data['words'][1] + ':' + 
     data['words'][2] + 
    '</span></p></div>'
  description2 = ''
  #Load and modify the KML template
  kmlFile = open('home/templates/response.kml', 'r')
  result = kmlFile.read() 
  result = result.replace("%lon%", str(lon)).
    replace("%lat%", str(lat)).
    replace("%elevation%", str(elv)).
    replace("%description1%", description1).
    replace("%description2%", description2).
    replace("%title%", "What3Words Test")
  return result

• 4. Modified the ArcGISEarth.exe.config file to format the URL call. Here’s the example for my call to the What3Words CherryPy command:

...
 <add key="urlwithpos" 
value="http://127.0.0.1:8585/callWhat3Words?lon=%LONGITUDE%&amp;lat=%LATITUDE%&amp;elv=%ELEVATION%"
/>
...

• 5. Restart Earth, zoom in somewhere, and CTRL-RIGHT-CLICK… and this is what I see:

You could conceivably call any URL that can accept coordinates and which could return KML. If you launch a web page you could, for example, call other services or data links that could add data into your workspace.

Here are a few tips:

• Use the urlwithpos value for the key attribute on the add element under the ServiceURL element to enable this feature
• When formatting the URL in the config file, ampersand needs to be represented as &
• %LONGITUDE% – Key value that represents the longitude of the point clicked
• %LATITUDE% – Key value that represents the latitude of the point clicked
• %ELEVATION% – Key value that represents the elevation of the point clicked, currently in meters
• %HEADING% – At the ArcGIS Earth 1.1 release, we will be adding a value to represent the heading that the map view is currently facing

Let us know if you are able to use this to add any interesting capability into Earth! Later in the year we are planning on releasing an API or SDK and we really look forward to seeing what users will be able to do then.

See you around the #DevSummit!