Geographical Microsyntax

This document identifies three geographical notation formats that may be appropriate as microsyntax for geosocial applications. It lists and describes each such format. It also provides guidance on how to apply microsyntax to ActivityPub content and objects.

This is an experimental specification and is undergoing regular revisions.

Microsyntaxes let users with constrained composition environments add structured data to an Activity Streams 2.0 object with minimal input overhead. Examples include using the @ symbol to add a Mention, and the # symbox to add a Hashtag.

Microsyntaxes have the benefit that users can start using them as a social convention, with no effect on data storage or presentation, which is later adopted by software developers. Besides the mention and the hashtag, "cashtags", "retweets" and other social conventions began in this way.

This document introduces two microsyntaxes for attaching location information to an ActivityPub object. Several notations were considered, including what3words and MapCode, but licensing issues make those notation formats incompatible with an open standards process.

When geographic microsyntax is added to source text for an object, it can result in modifications to object itself. The second section describes how social microsyntax can affect the content and/or location properties of an ActivityPub object.

Of course, the geographical microsyntax may not be used by the creator's client or server to modify the object. The receiver's client, or even a third-party data aggregator, can use the microsyntax directly instead.

Geographical microsyntax

Open Location Codes

Plus Codes, also called Open Location Codes, are a format for encoding lat/lon pairs efficiently. The algorithm was developed by Google and released under the Apache license. Plus Codes encode latitude-longitude pairs.

Documentation Plus Codes
Pattern(s)
  • 10 or more letters and numbers joined by a "+"
  • 6 or more letters and numbers joined by a "+", followed by a comma-separated location identifier
Examples
  • 87C4VXQ7+QV
  • GV3C+8X, London, United Kingdom
Web page URI template https://plus.codes/{pluscode}
ActivityPub object URI template (none)

OpenStreetMap identifiers

OpenStreetMap is a user-generated world-wide map. It represents places as points ("nodes"), lines ("ways"), and polygons ("relations"). The data is available under the Open Data Commons Open Database License.

Documentation Elements
Pattern(s)
  • "N" + (number)
  • "R" + (number)
  • "W" + (number)
Examples
  • N2598721627
  • W5013364
  • R2689445
Web page URI template https://www.openstreetmap.org/{type}/{number}
ActivityPub object URI template https://places.pub/{type}/{number}

Without automated help, looking up and encoding lat/lon pairs or OpenStreetMap ids for a location can be tedious for users.

Geoslash is a microformat for treating natural-language strings as location identifiers. Geoslash lets a user trade some accuracy and precision for ease of authoring. Saying "I am in /Berlin/" sets the location to Berlin. It's up to downstream processors to use contextual information to decide if that means Berlin, Germany or Cafe Berlin in San Juan, Puerto Rico.

The original proposal for Geoslash included a time aspect: "I am in /Berlin: this week/". How to treat the time aspect of Geoslash microsyntax is outside the scope of this document. Geosocial processors can simply omit the time aspect of the Geoslash data.

One possible resolution for a Geoslash item is to use a search engine like Nominatim to resolve the text into a likely OpenStreetMap node, way or relation, and then link to the page or ActivityPub object for that OSM identifier.

Documentation Geoslash
Pattern(s)
  • Opening / followed by natural language text to a closing slash or end of text
  • Opening / followed by natural language text to a closing colon or end of text
Examples
  • Here is a photo of /Mission Viejo, CA/ with birds
  • I just checked in for my flight /YVR
  • I will be in /Hong Kong: July 17-24/ if you'd like to meet
Web page URI template https://www.openstreetmap.org/{type}/{number}
ActivityPub object URI template https://places.pub/{type}/{number}

Applying microsyntax to ActivityPub objects

This section describes ways that ActivityPub applications can apply geographical microsyntax.

location property

The location defined in the microsyntax can be converted to an Activity Streams Place object, and embedded in the location property of the encoding object. The Place object can have id or url properties.