All versions of The Photographer’s Ephemeris use a standard URL format. You can build your own URLs (for example, via a scripting tool or by manually editing the address in your browser) and use them freely – they’ll open in the web or iOS app as normal.
Standard TPE URL Parameters Example
Here’s an example:
In this example, the parameters are used as follows:
| Parameter | Value | Usage |
|---|---|---|
| ll | 63.939897,-17.369803 | Red map pin location. Latitude, longitude coordinate pair in decimal degrees. Negative longitude is west. |
| center | 63.9586,-17.3145 | Centre of map. Latitude, longitude coordinate pair in decimal degrees. Negative longitude is west. |
| z | 9 | Zoom level. Value between 1 and 21 (max value may be lower with certain map types selected) |
| spn | 0.64,3.09 | Span. Decimal degree pair showing latitude and longitude span. Equivalent to zoom level. Use either. |
| dt | 2017-01-25T17%3A04%3A00.000Z | Date/time. Date and time in ISO 8601 format to millisecond precision. ‘%3A’ is the URL-encoded form of ‘:’. The legacy iOS form yyyyMMddHHmmssxx (e.g. 20170125170400+0000) is also accepted as a fallback. |
| sll | 63.972628,-17.052924 | Secondary pin location (optional). Latitude, longitude coordinate pair in decimal degrees. Negative longitude is west. |
Example with Building Heights
Advanced TPE URL Parameters Example
A more advanced example that includes building heights and footprint sizes:
Here’s a list of the parameters not mentioned above:
| Parameter | Value | Usage |
|---|---|---|
| sh | 5.00 | Primary object height in metres. e.g., the height of the camera above the ground |
| ch | 30.00 | Secondary object height in metres. e.g., the height of a building |
| sw | 10 | Building footprint in metres at primary pin |
| cw | 60 | Building footprint in metres at secondary pin. |
Visual Search URL Parameters
The following URL parameters are reserved for future use with the Visual Search function.
| Parameter | Example | Usage |
|---|---|---|
| vsaa | vsaa=124.52,4.12,2,1 | Azimuth, Altitude Target. Comma-separated az/alt target followed by az/alt tolerance, all in degrees |
| vsaltp | vsaltp=false | Altitude Priority. Determines whether search interpolates for altitude (true, default) or azimuth (false) |
| vsd | vsd=15768000 | Search Duration. Search period length, in seconds, from app selected date/time (use the ‘dt’ param to set date/time). Currently only four values are honoured: 15768000 (~6 months), 31536000 (1 year), 63072000 (2 years), 157680000 (5 years). Other values are ignored. |
| vsr | vsr=false | Range Mode. Range mode (true, default) or single target mode (false). In Range Mode, the search checks for the target body crossing the bounds of the az/alt region specified by ‘vsaa’ parameter. In Single Target Mode, we interpolate the priority |
| vsb | vsb=moon | Body. ‘sun’, ‘moon’, or ‘gc’ (galactic centre). The body of interest. |
| vsa | vsa=-1 | Disk Alignment. -1, 0, or 1. For bodies with known semidiameter (sun, moon), specifies whether the body should be aligned using the bottom (-1), centre (0, default), or top (+1) of the disk |
Visual Search Filters
Visual Search Filters can be encoded in the URL using the ‘vsf’ parameter, as follows:
vsf=b:[body]|p:[property]|v:[value_range]
where:
- body: sun, moon or gc
- property: az (azimuth), alt (apparent altitude), ill (illuminated fraction), wax (waxing), sd (semidiameter)
- value_range: comma-separated minimum and maximum values, e.g. 90,100 for azimuth (degrees), 0.95,1 for the Moon’s illuminated fraction, 0,0 for waxing = false or 1,1 for waxing = true
The ‘vsf’ parameter can specify multiple filter conditions using semicolon separation, e.g.,
vsf=b:moon|p:ill|v:0.95,1;b:sun|p:alt|v:-6,0
The example requires the Moon’s disk to be > 95% illuminated and for the Sun to be between 6 and 0 degrees below the horizon (i.e. civil twilight).
New in TPE Web v4
TPE Web v4 introduces a Field of View overlay that draws the camera’s framed scene on the map. The overlay’s state – bearing, focal length, distance, gear selection and so on – can be encoded in the URL and is automatically included in shareable links when the overlay is active.
Field of View parameters
Two coexisting groups of parameters describe the same underlying state, mirroring the Freeform / Gear options in the FOV side panel’s mode switcher. The freeform parameters encode the resulting cone in degrees so a recipient can render it regardless of which gear they own. The gear parameters encode the exact camera, lens, focal length and teleconverter so a recipient who owns the same gear round-trips back to the precise configuration.
When the overlay is active in the app (a camera and lens are selected), both groups are emitted side-by-side. When constructing URLs by hand, the freeform parameters alone are sufficient to draw the cone; the gear parameters are optional.
Freeform parameters (camera-independent)
| Parameter | Example | Usage |
|---|---|---|
| fovb | fovb=137.50 | Camera bearing. Compass heading the camera is pointing along, in degrees (0–360). |
| fovhfov | fovhfov=24.40 | Horizontal field of view, in degrees (0–360). |
| fovvfov | fovvfov=16.50 | Vertical field of view, in degrees (0–180). |
| fovd | fovd=420.0 | Subject distance, in metres. Where the camera is focused along the bearing. |
| fovo | fovo=l | Orientation: l for landscape, p for portrait. |
| fovov | fovov=1 | Overlay visible: 1 to draw the cone on the map, 0 to hide. |
Gear parameters (round-trips exact gear)
| Parameter | Example | Usage |
|---|---|---|
| fovcam | fovcam=cam-uuid | Active camera device ID. Resolved against the recipient’s camera library. |
| fovlens | fovlens=lens-uuid | Active lens device ID. Resolved against the recipient’s lens library. |
| fovfl | fovfl=70.0 | Focal length, in millimetres. Clamped to the lens’s range when the lens is resolved. |
| fovtc | fovtc=1.4 | Teleconverter factor: one of 1.0, 1.4, 1.7, 2.0, 3.0. |
| fovtcsl | fovtcsl=1.20 | Teleconverter stop-loss override, in stops (0–10). Optional manual override for non-standard teleconverters. |
| fovr | fovr=m | Distance range: c (close, up to 1 km), m (mid, up to 15 km), f (far, up to ~322 km). Controls the subject-distance slider’s maximum. |
Example URL
This drops a pin in Boulder, CO at sunset on 15 June 2026, with the camera pointing south-east and framing a 24.4° × 16.5° scene 420 m away.
