Open GeoFeed Protocol

Overview

OGP is built on a simple premise: every piece of local activity — a restaurant's daily special, a store opening, a neighborhood event — happens at a specific place in a specific part of the world. OGP gives that place a stable, human-readable identifier and defines how activity feeds anchored to it are published, discovered, and consumed.

The protocol has three layers:

The registry and the protocol spec are operated by geofeed.ai and licensed Apache 2.0. Any implementation — including Findera — is a conforming server that can register with the public registry.

SubdivisionPath

A SubdivisionPath is the canonical identifier for a geographic subdivision. It is a slash-separated sequence of lowercase slugs, starting with an ISO 3166-1 alpha-3 country code.

Alpha-2 normalization

Paths may begin with a 2-letter country code (ISO 3166-1 alpha-2). They are silently normalized to alpha-3. br/sp/sao-paulo becomes bra/sp/sao-paulo. All canonical storage and API responses use alpha-3.

Short paths

Some contexts expose a short form that omits the country prefix when the country is implicit: sp/sao-paulo/tatuape. Short paths are display-only — canonical storage and all API responses always use the full path.

Subdivision Context

A SubdivisionPath is always resolved within a context. A context defines which geographic hierarchy is active for a country. The same physical subdivision can have different paths in different contexts.

Context IDs follow the format {COUNTRY}-{scheme}, e.g. BRA-administrative. Each country has exactly one default context. When a context is not specified in a request, the country's default context is used.

Context is never embedded in the path string itself. It is passed as a query parameter:

Hierarchy & local_level

Every subdivision has a SubdivisionType with a numeric local_level that defines its position in the hierarchy. Higher values = more granular.

The minimal_local_level parameter on reverse geocoding endpoints controls response granularity. For example, minimal_local_level=3 returns at most the municipality level — useful when neighborhood precision is unnecessary or unavailable.

Parent-child relationships

Relationships are stored as a many-to-many through table scoped by context (SubdivisionHierarchy). A subdivision can have multiple parents within a context — e.g., a neighborhood that spans district boundaries. Root nodes are self-referencing: parent == child.

GeoFeed Format

GeoFeeds use the ActivityStreams 2.0 wire format (as used by ActivityPub). OGP extends it with a single geopath field on any Place or Object.

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://geofeed.ai/ns/v1"
  ],
  "type": "Create",
  "actor": {
    "type": "Organization",
    "id": "https://findera.app/actors/salao-gi-matos",
    "name": "Salão Gi Matos",
    "geopath": "bra/sp/sao-paulo/tatuape"
  },
  "object": {
    "type": "Note",
    "geopath": "bra/sp/sao-paulo/tatuape",
    "content": "Agenda aberta para esta semana!",
    "published": "2025-03-23T10:00:00Z"
  }
}

Because OGP uses ActivityStreams, any Fediverse client can consume an OGP feed without modification. The geopath field is additive — it doesn't break existing ActivityPub implementations that don't understand it.

Actor types

Any Schema.org type may be used for actors. Commonly used types:

Registry Architecture

The registry operates like DNS root servers: it knows what geopaths exist and which servers are authoritative for them, but delegates actual content to registered servers. Anyone can register as a content server without permission from the registry operator.

Server types

API Endpoints

All endpoints are read-only (GET). The same data is served via three subdomains in different formats. Server registration is not yet open — contact geofeed.ai.

Hint System

Reverse geocoding responses include a hint field that tells the consumer where the result originated:

Both values are valid GeoPath responses. The subdivision field is only populated on internal hints. Consumers should handle both gracefully.