Undocumented Features: TPE for iOS URL Scheme


Back in July 2012, we released version 2.2 of TPE for iOS. Amongst the new features (shadow lengths, moon perigee/apogee, crescent moon visibility, help overlays) was one that has until now remained largely a secret: an app-specific URL scheme.

An app URL scheme allows you to cause the app to open and take a specific action. For example:


will open TPE on your iThing and set the red map pin to the summit of Ben Nevis, Scotland. ll denotes latitude/longitude, a decimal coordinate pair, separated by a comma (following Google’s style for Maps URLs).

Note: these links will only function on a device with TPE for iOS installed.

We can take things a little further and specify the map region we’d like to display. This is best thought of as the zoom level for the displayed map. For example:


shows the whole state of Colorado. Yes (and I hadn’t realised this until preparing this example), Colorado is 4° latitude by 7° longitude (although those straight state-lines of course hint strongly at a lawmaker with a ruler and map!). In this case spn denotes map region span in degrees.

Finally, we can optionally specify a date to display. For example:


takes us to Cairns in Queensland Australia for the 2012 total eclipse of the sun, or:


to Washington DC for the lighting of the US National Christmas Tree on December 6.

At the moment, you can’t specify a certain time of day, only the date – that’s something we plan to add in the future.

(One thing I noticed while writing this post is that occasionally on changing to a new location, the time zone will appear incorrectly, resulting in some mixed up data. It appears this is an intermittent bug: I’ve only seen it once, but we’ll need to do some digging to get it fixed. Still, I decided it was worth sharing the information nonetheless.)

Also, we’ll be using the URL scheme to add support to future versions of TPE to allow you to Tweet or share via FB your planned shots.

In the meantime, if you click these links while reading this post on an iDevice with TPE installed, you can see how the scheme works. And feel free to start sharing your own links straightaway! If you have any URL scheme support features you’d like to see added, drop us a line.

Here’s a reference on how the URL scheme works as of TPE for iOS 2.2:

Go to coordinates

URL: ephemeris://view?ll=[latitude,longitude]
Values: numeric latitude between +90 and -90 degrees; numeric longitude between +180 and -180 degrees (west is negative); comma separated

Go to coordinates and map region

URL: ephemeris://view?ll=[latitude,longitude]&spn=[height,width]
ll: as above
spn: numeric latitude span between 0 and 180 degrees; numeric longitude span between 0 and 360 degrees; comma separated

Go to coordinates and date

URL: ephemeris://view?ll=[latitude,longitude]&dt=[datetime]
ll: as above
dt: date/time in format yyyyMMddhhmmssZ, e.g. 20120921000000+0000. Time of day and time zone are reserved for future use, and should be set to midnight GMT (i.e. 000000+0000)