nips/G0.md

NIP-G0

Geospatial Tags for Nostr Events

draft optional

This NIP offers a standard for geospatial tagging in Nostr events. It defines a flexible structure to designate an event's location and area of impact or relevance. By implementing this standard DVMs, clients, and relays can enable location-based search, filtering, and user discovery through location based notes.

Goal

Geospatial data is helpful for many use cases, such as:

• Localized news or alerts to be tagged by outlets to target audience and strengthen search.
• Bot and DVM content filtration handles to allow user custom feed tweaking.
• Events with regional or global impact can be filtered according to interests.
• Community engagement based on proximity and better connections allowed for users to find users of interest.
• Privacy-conscious clients can allow tagging by creators to share relevance of content and controled-precision while sharing any of the creator's own location.

This proposal defines a lightweight and hierarchical tagging approach, while ensuring backward compatibility.

Specification

This NIP defines two primary tag types: geo_loc and geo_rel and one additional convenient compatibility tag w3w.

1. geo_loc [optional, repeatable] The geo-location of the event.

Represents the event’s origin location. Each tag specifies a geographic or political level. Multiple tags may be used to define a hierarchy. This structure may be quite flexible in eventual usage, but by predefining a base set, client usage benefits from establishing early consistency:

• "location": (optional) Precise point as GPS long,lat coordinates.
• "w3w": (optional) Precise point on earth using what3words.
• "g": (optional) Precise point as a geohash as in NIP-52.
• "dist": (optional,repeatable) Ward, Neighborhood or sub-municipal area.
• "muni": (optional,repeatable) Specified municipality, city, town, etc.
• "metro": (optional,repeatable) Metropolitan area that is multi-municipal in context.
• "county": (optional,repeatable) County or similar administrative division of a state or province.
• "reg": (optional,repeatable) Region named or general, non-state, non-province.
• "canton": (optional,repeatable) Canton or similar administrative division of a nation.
• "state": (optional,repeatable) State specified.
• "prov": (optional,repeatable) Province specified.
• "nat": (optional,repeatable) National context.
• "cont": (optional,repeatable) Continental context.

Example: Location with heirarchy.

["geo_loc", "muni", "Jefferson City"]
["geo_loc", "reg", "Missouri"]
["geo_loc", "nat", "USA"]

Example: Precise location.

["geo_loc", "w3w", "farm.vines.index"]
["geo_loc", "g", "9yy7vdxxy2g6s6qf"]

2. geo_rel [optional, repeatable] Event relevance or impact.

Represents the geographic or political areas affected or relevant to the event. The parameter structure mirrors geo_loc and can also include multiple locations to define broader or specific impacts.

Examples:

["geo_rel", "muni", "Kansas City"]
["geo_rel", "muni", "St. Louis"]
["geo_rel", "state", "Missouri"]
["geo_rel", "nat", "USA"]

No geo_rel tag present could indicate a global relevance or this tag could remove ambiguity:

["geo_rel", "global"]

3. w3w [optional, repeatable] Precise location(s).

Represents the geographic or political areas affected or relevant to the event. The parameter structure mirrors geo_loc and can also include multiple locations to define broader or specific impacts.

Examples:

["w3w", "///farm.vines.index"] # The triple-slash w3w standard syntax.
["w3w", "farm", "vines", "index"] # The 3 words as three values.
["w3w", "farm.vines.index"] # The 3 words dot-separated

Added Standardized Tags (to update list in README)

name	value	other parameters	NIP
geo_loc	The geo-location of the event.	location, g, w3w, dist, muni, metro, county, reg, canton, state, prov, nat, cont	NIP-G0
geo_rel	The event impact or relevance.	location, g, w3w, dist, muni, metro, county, reg, canton, state, prov, nat, cont	NIP-G0
w3w	A what3words precise location.	See examples for parameters.	NIP-G0

Usage Notes

• Both geo_loc and geo_rel are optional.
• Tags are designed to be lightweight and compatible with existing Nostr infrastructure.
• Clients and relays that do not recognize these tags will ignore them without disruption.

Rationale

This design leverages Nostr’s existing flat tagging structure to ensure compatibility and ease of use:

• Flexibility: Supports diverse use cases, from hyperlocal events to global phenomena.
• Privacy: Allows generalized or anonymized location tagging.
• Compatibility: Relies on standard tag processing, ensuring backward compatibility.

Security Considerations

Geospatial data may raise privacy concerns. Event creators should carefully select the level of detail in location and impact tags to balance utility with privacy. Client-side tools should allow users to obfuscate or anonymize location data where appropriate and have visibility to the tags being set to notes by default or per note selections.

Backward Compatibility

This NIP does not affect existing Nostr functionality. Tags introduced here are optional and will be ignored by clients or relays that do not implement this NIP.

Example Use Case

Missouri State Law Example:

{
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "pubkey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": 1702137600,
    "kind": 1,
    "tags": [
        ["geo_loc", "muni", "Jefferson City"],
        ["geo_loc", "state", "Missouri"],
        ["geo_loc", "nat", "USA"],
        ["geo_rel", "muni", "Kansas City"],
        ["geo_rel", "muni", "St. Louis"],
        ["geo_rel", "state", "Missouri"]
    ],
    "content": "Missouri has passed a new state law that directly impacts municipal regulations in Kansas City and St. Louis. The law, focused on zoning changes for housing developments, applies only to these cities while exempting others in the state."
}

Reference

• NIP-01: Basic Event Structure
• NIP-52: Event Categorization and Metadata offers g and location tags.
• Geo heirarchies