Maps · EtherPK User Docs

A map in a document shows places and routes: the campsites on a trip, the walk you did, the pubs near a client's office. Type /map to add one, then find a place, paste a link or draw a route. The places are kept in the document itself as lines of text, so they sync, export and back up with the rest of your notes. The Map View then shows every place and route that belongs to a concept on one map, gathered from across your graph.

Maps work on a phone as well as a computer, and they're free to use. Finding a place by its postcode works for everyone, for UK postcodes and US ZIP codes. Searching by name or address, and naming a place you put on the map after the place nearest it, come with Sync+ (Managed Sync), because each search costs us a little to answer. Everything else about maps, coordinates and links included, works for everyone.

Maps are an extension that comes with EtherPK. Settings and Extensions → Extensions switches them off on a device where you don't want them (Graph Settings). While they are off, each map shows as the lines of text it is kept as, and a page holding one can't be published from that device.

Add a map

Type /map in a document and choose Map. On an empty line the map takes that line's place, and on an empty bullet the map goes beside the bullet's dot. On a line with text, the map goes on new lines beneath it, and beneath a bullet it becomes part of that bullet's block. The new map's search box is ready for you to type in.

Add a place

Type into the map's search box and press Enter, or select the search button at the end of the box. A name or a postcode is also looked up when you stop typing for a moment. The box reads all of these on your device, without asking any service:

Coordinates, latitude first, as Google Maps copies them: 50.7486, -4.0789. Letters for the hemisphere work too (50.7486° N, 4.0789° W), and so do degrees, minutes and seconds (50°44'55"N 4°04'44"W).
A link copied from Google Maps, Apple Maps or OpenStreetMap, or a geo: link, including OpenStreetMap's short links (https://osm.org/go/…). When the link names the place, the name comes with it. You can paste everything a phone's Share gives: the place's name before the link names the place when the link doesn't.
A Plus Code, such as 9C2VPX45+PJ. A short one, such as PX45+PJ, is found near the middle of what the map shows.

A Google short link, such as one starting https://maps.app.goo.gl/, is opened by your Sync Server, because a browser can't open one itself. This works for any account. A short link from a phone gives the place's name and address but not where it is, and so does a link to a Google search, so the map searches for them, which needs Sync+. When the map can't do either, it says so: open the link in your browser and copy the full address from the address bar instead.

A postcode is found for everyone, from postcode files EtherPK's map host keeps:

A UK postcode, with or without its space, such as PO30 1AE. Northern Ireland's postcodes aren't included yet.
A UK postcode district on its own, such as PO30, which finds the middle of the district.
A US ZIP code with its four extra digits, such as 90210-1234. A plain five-digit ZIP code such as 90210 counts when your browser is set to the United States, because many countries use five digits.

The place found is named with its postcode, which you can change.

With Sync+, or on a self-hosted Sync Server that has search set up, you can also type a name or an address, such as Edinburgh, and choose the place from the list. A postcode the files don't have, such as another country's, goes to that search too, and a full UK postcode only finds a place with exactly that postcode.

You can also choose Add a place and click the map where the place is. Either way you're asked for a name. Type it and press Enter.

With Sync+, a place you click on the map, or type as coordinates or a Plus Code, is offered the name of the place nearest it, or of the village or town it's in, with its address underneath. Keep it or type over it. A name you start typing first is never replaced.

Draw a route

Choose Draw a route and click the map at each point along the way. The panel shows how many points you've placed and how long the route is so far. Undo point takes back the last one, and Finish asks for the route's name. A route joins its points with straight lines: it isn't snapped to roads or paths.

Import a GPX recording

Choose Import a GPX file… from the map's More menu, or drop a .gpx file on the map. Each track or planned route in the file becomes a route, and each waypoint becomes a place. The original file is kept in your graph with your images and files, and the route links to it, so nothing in the recording is lost. The map draws a simpler copy of a track that stays within a few metres of the original.

Change a place or a route

Click a place's pin, or a route's line, to choose it. You can then:

Rename it.
Move a place: drag its pin, or click the map where it should go.
Copy coordinates, to paste into another app.
Open in maps app, for directions and the like. Apple devices open Apple Maps, and others open Google Maps.
Remove it. A notice offers to put it back for a few seconds, and the document's undo (Ctrl+Z, or Cmd+Z on a Mac) brings it back after that.

Each change is an ordinary edit of the document, so undo and redo work as they do for typing, and a change made on another device shows up as you watch.

Fold, edit as text or delete a map

Fold the map turns it into a single line that says what it holds, such as "Map, 3 places and 1 route". A folded map loads nothing. Whether a map is folded is remembered on this device only.
Edit as text in the More menu shows the lines behind the map in the document. The map comes back once you move the cursor out of them.
Delete map in the More menu removes the whole map. The document's undo brings it back.

The text behind a map

A map is a fenced block whose first line is ```map, with one line for each place or route:

```map
Pebble Cove Campsite @ 50.74860, -4.07890
Coast walk @ 50.74860, -4.07890 > 50.75112, -4.08240 > 50.75300, -4.09000
Ridge walk @ 54.60120, -3.13410 > 54.60500, -3.14000 (../assets/ridge-walk.a1b2c3d4.gpx)
```

Each line is a name, then @, then a latitude and a longitude in decimal degrees. A line with one point is a place, and a line with points joined by > is a route. A route imported from a GPX file ends with a link to the original file in brackets. A line the map can't read is kept exactly as written, and the map says how many there are.

Which places belong to a concept

A place or route belongs to the same concepts as a task written where its map is ([[Kanban Boards]] explains the rule). So a map on the Campsites page belongs to Campsites, and so does a map under a bullet that links [[Campsites]] on a trip page. A place's name is plain text: write the link on the line or the bullet the map sits under, not inside the map.

The Map View

The Map View shows every place and route that belongs to a concept, framed so they all fit, with a list beside it grouped by the document each is written in. To open one:

right-click a document's tab, or a link to the concept, and choose Open Map View (long-press on a phone)
type / in a document and choose Open Map View, which shows the map of the concept your cursor is in, named beside the command, and asks which one when there are several
type / and choose Graph Map View, or select Graph Map View under Today's journal in the left sidebar, for every place and route in the graph.

Choose a place in the list or on the map to see its coordinates, and to Show in document, which opens its document at its map with the place chosen, in front of the map in the same pane, Copy coordinates or Open in maps app. Where several places share one spot, such as one place written in several documents, choosing it lists them all, each with Show in document, and the list beside the map scrolls to them. Type in the filter box to narrow the list and the map to the names and documents that match. Where many places are close together the map shows how many there are in a circle. Click the circle to zoom in, or to list its places when they share one spot. The Map View changes nothing: you edit places in their maps.

Each Map View has its own address, so the browser's back button returns to it, and a concept's map follows the concept when you rename it.

Moving around a map in a document

The mouse wheel scrolls the document past a map, as it does past an image. Hold Ctrl (Cmd on a Mac) and use the wheel over a map to zoom the map, or use its + and - buttons. On a phone, move the map with two fingers. In the Map View the map moves with one finger or the mouse, and the wheel zooms it, as maps usually do. To make the document's text larger or smaller, press Alt+= or Alt+- (Keyboard Shortcuts).

A map is a code block that EtherPK draws as a map, the way it draws a diagram (Code Maths And Diagrams). Move the cursor into it with the arrow keys and the map shows its lines of text instead, ready to edit. Move the cursor out and the map is drawn again. A click on the map itself is the map's: it moves the map or adds a place, and leaves the cursor where it was. To delete a map, choose Delete map from its More menu, or delete its lines as text.

Maps on a published site

A map on a published page is a picture of the map, with the places' names beside their pins and the map's credit in a corner. The picture's description names what's on the map, and the site never holds the map's coordinates. Publishing draws each map, so it needs a connection, and a map that can't be drawn stops the publish and says which page it's on (Publishing Your Notes As A Website).

Use your own Mapbox token

With your own Mapbox access token, your maps are drawn over Mapbox's street map, and a Satellite switch on each map and Map View shows Mapbox's satellite imagery with roads and names. Each device remembers whether it shows the map or the satellite imagery. The places on a map don't change, and a published page's picture of a map is always drawn over EtherPK's map.

You need:

A Mapbox account with a payment card added. Mapbox serves satellite imagery only to such an account, and only such an account can restrict a token to an address. Mapbox bills by use beyond a free allowance (Mapbox pricing).
A public token, with its default public scopes, restricted to the address you use EtherPK at, such as https://app.etherpk.com.

To set it up:

In your Mapbox account, open Tokens and create a token. Keep its public scopes, and under URL restrictions add the address you use EtherPK at.
Copy the token, which starts with pk..
In EtherPK, open Settings and Extensions → Extensions, open Settings under Maps, paste the token into Mapbox access token and choose Save.

You're responsible for following Mapbox's terms of service when you use your token. The token is one of your extension settings (Graph Settings), so once your account syncs a graph it follows you to your other devices. If Mapbox doesn't accept the token, each map says so and is drawn over EtherPK's map instead.

Maps and privacy

The places on a map are text in your document. They're encrypted and synced like the rest of it.
Showing a map fetches the map's images from EtherPK's map host, which learns which area is on screen, though never your places or their names. With your own Mapbox token they come from Mapbox instead, which learns the same, and your token.
Coordinates, Plus Codes and map links are read on your device. A postcode fetches one small file from EtherPK's map host, which learns only the postcode district. A search by name goes to your Sync Server, which passes it to the search service and keeps no record of it. So does a place's position when it's offered the nearest place's name.
A Google short link goes to your Sync Server, which asks Google where it leads, reads only the answer's address, and keeps no record of the link.
Use search and link services, in the Maps extension's settings (Settings and Extensions → Extensions → Maps → Settings), is on until you turn it off. Off, a map asks no search service and opens no short link, so searching by name, the nearest place's name and short links stop. Coordinates, Plus Codes, map links and postcodes still work, and your own Mapbox token still draws Mapbox's map. The setting follows you to your other devices where your account syncs a graph.
Maps aren't drawn in a protected document, and /map isn't offered there, because showing a map would tell the map host something about what's in the document (Protected Documents). A map that's already there is shown as its text.

Running EtherPK yourself

A copy of the Client you run yourself (Running EtherPK On Your Own Computer) draws its maps over EtherPK's map host too, and reads coordinates, Plus Codes and map links on your device as the hosted Client does, and finds postcodes from EtherPK's map host. Searching for a place by name goes through the server a graph syncs with, so with no Sync+ the map asks for coordinates, a postcode or a link instead. Your own Mapbox token works there too, restricted to that copy's address.

Postcode data

UK postcodes come from the ONS Postcode Directory, under the Open Government Licence:

Source: Office for National Statistics licensed under the Open Government Licence v.3.0

US ZIP codes come from the U.S. Census Bureau's ZIP Code Tabulation Areas, which are in the public domain. A ZIP code with no tabulation area, such as a PO box's, isn't found.