mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-22 16:35:52 -05:00
5add1354df
Introduction of NIP to standardize event geospatial tagging for location of event origin and location area of event relevance, with both being hierarchical, offering flexibility for users and systems to filter and improve content relevance to user interest when proximity, politics and geography matters.
143 lines
6.7 KiB
Markdown
143 lines
6.7 KiB
Markdown
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](https://en.wikipedia.org/wiki/What3words).
|
||
- `"g"`: (optional) Precise point as a [geohash](https://en.wikipedia.org/wiki/Geohash) as in [NIP-52](52.md).
|
||
- `"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.
|
||
```json
|
||
["geo_loc", "muni", "Jefferson City"]
|
||
["geo_loc", "reg", "Missouri"]
|
||
["geo_loc", "nat", "USA"]
|
||
```
|
||
|
||
Example: Precise location.
|
||
```json
|
||
["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:
|
||
```json
|
||
["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:
|
||
```json
|
||
["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:
|
||
```json
|
||
["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](README.md))
|
||
|
||
| 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](G0.md) |
|
||
| `geo_rel` | The event impact or relevance. | `location`, `g`, `w3w`, `dist`, `muni`, `metro`, `county`, `reg`, `canton`, `state`, `prov`, `nat`, `cont` | [NIP-G0](G0.md) |
|
||
| `w3w` | A what3words precise location. | See examples for parameters. | [NIP-G0](G0.md) |
|
||
|
||
|
||
### 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:**
|
||
```json
|
||
{
|
||
"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](01.md): Basic Event Structure
|
||
- [NIP-52](52.md): Event Categorization and Metadata offers `g` and `location` tags.
|
||
- [Geo heirarchies](https://wikitravel.org/en/Wikitravel:Geographical_hierarchy)
|