Observer Setup

Everything Craft computes — pass predictions, azimuth/elevation, rise and set times, Doppler shift — depends on knowing exactly where you are on Earth. This page covers how to configure your observer location and what each setting controls.

Environment variables

Observer location is set in the .env file at the project root. Five variables define your position:

.env

OBSERVER_LAT=36.1627
OBSERVER_LON=-86.7816
OBSERVER_ALT=182
OBSERVER_NAME=Nashville
OBSERVER_GRID=EM66lp

Variable	Description	Units	Example
OBSERVER_LAT	Latitude	Decimal degrees, north positive	36.1627
OBSERVER_LON	Longitude	Decimal degrees, east positive	-86.7816
OBSERVER_ALT	Altitude above sea level	Meters	182
OBSERVER_NAME	Display name for your location	Free text	Nashville
OBSERVER_GRID	Maidenhead grid locator	4 or 6 character grid	EM66lp

Tip

After changing observer variables, restart the API container for the new values to take effect:

docker compose restart api-dev

Finding your coordinates

From a map

The simplest way: open Google Maps, right-click your location, and the coordinates appear at the top of the context menu in latitude, longitude format. Copy them directly.

OpenStreetMap works the same way — click a point and the coordinates show in the sidebar.

From your GPS

If you have a handheld GPS or a phone with a GPS app, stand at your antenna location and read the coordinates. This is the most accurate method, especially if your antennas are at a different elevation than your house.

From your radio

Many modern transceivers with built-in GPS report coordinates in the APRS format (degrees and decimal minutes). Convert to decimal degrees:

N 36 09.762  W 086 46.896

Latitude:   36 + (09.762 / 60) =  36.1627
Longitude: -(86 + (46.896 / 60)) = -86.7816

Note

West longitudes and south latitudes are negative. Nashville, Tennessee is 36.16, -86.78. Sydney, Australia is -33.87, 151.21.

Altitude matters

OBSERVER_ALT is your altitude above mean sea level in meters, not above ground level. This affects pass calculations in two ways:

1. Horizon distance — Higher observers see satellites earlier on the horizon and lose them later. A hilltop station at 500 m picks up a few extra seconds of pass time compared to a station at sea level.

2. Parallax — For objects in low Earth orbit (under ~2,000 km), a difference of even 100 meters in observer altitude shifts the computed position slightly.

For most amateur stations, getting within 10 meters is plenty accurate. If you are unsure of your elevation, look up your address on a topographic map or use a tool like FreeMapTools Elevation Finder.

Tip

If you have rooftop antennas, add the building height to your ground-level elevation. An antenna on a 15 m tower at a site that is 200 m above sea level should use OBSERVER_ALT=215.

Maidenhead grid locator

OBSERVER_GRID is a Maidenhead Locator System grid square. This is the standard position encoding used in amateur radio — you will see it on QRZ pages, in WSJT-X, and in contest exchanges.

A grid square encodes latitude and longitude into a compact string:

Characters	Name	Precision
2 (e.g., EM)	Field	~1,000 km
4 (e.g., EM66)	Square	~100 km
6 (e.g., EM66lp)	Subsquare	~5 km

Craft uses the grid square for display purposes and for compatibility with amateur radio software that expects grid-based position data.

Finding your grid square

Several tools convert coordinates to Maidenhead grids:

• QTH Locator Map — type an address or click the map
• K2DSL Grid Square Locator — coordinates to grid and back
• ARRL Grid Locator — the league’s own tool

If you already know your 4-character grid from contest logging or QRZ, that works fine. The 6-character subsquare adds precision but is not required.

Note

You can verify your grid square against your coordinates. The first two characters encode 20-degree longitude and 10-degree latitude bands. EM covers longitudes -100 to -80 and latitudes 30 to 40 — which includes most of Tennessee. If your grid does not match your coordinates, one of them is wrong.

What changes when you move the observer

When you update your observer location, every location-dependent calculation shifts:

• Pass predictions recalculate AOS, TCA, and LOS times for your new position. A satellite pass that was 70 degrees maximum elevation from one location might only reach 20 degrees from another.
• “What’s Up” results change because different objects are above the local horizon at different locations.
• Azimuth and elevation for all tracked objects recompute relative to your new position. The same satellite at the same instant has a different az/el from Nashville than from London.
• Doppler shift calculations use observer position to determine the range rate between you and the satellite.
• Rise and set times for the Sun, Moon, and planets shift. These matter for optical satellite observing (you need the satellite sunlit and the sky dark).

The globe visualization itself does not change — it still shows the full Earth. But the ground track overlays, pass arcs, and horizon circle all anchor to the observer position.

Multiple observers

Craft currently supports a single observer location configured at startup. If you operate stations at multiple locations, swap the coordinates in .env and restart the API when you change sites.

For permanent multi-site setups, running separate Craft instances (each with its own .env) is the straightforward path. The Docker Compose setup is lightweight enough that two instances on the same host is practical.