FIP-X: Add location type as a valid Embed type.

[christopherwxyz]

FIP-X: Add location type as a valid Embed type.

Abstract

This FIP proposes adding support for Geo URIs as an embed option for cast messages in the Farcaster protocol. This addition will allow users to attach one or more location data points to their casts, enabling rich location-based features across various clients.

Problem

Currently, the Farcaster protocol doesn't have a standardized way to include location information in cast messages. This limitation prevents the development of location-based features that could enhance user experience and interaction across different clients. Some potential use cases include:

• Submitting casts with someone's current approximate location (e.g. ephemeral casts with location and an image)
• Offering recommendations based on a user's location (e.g., Farcaster meetups in the user's most visited city)
• Notifying users when someone they follow is visiting a specific location near them
• Finding past casts in a general area

While some clients (e.g. Warpcast, Checkin) have implemented location features at the client level, there's no protocol-level support for sharing this information in a way that all clients can process uniformly.

Specification

We propose extending the Embed message to include support for Geo URIs. This location data will be:

1. Represented using the standard Geo URI format described initially in RFC 5870
2. Of rough precision to protect user privacy
3. Erasable, allowing users to redact previously published locations
4. Able to represent multiple locations in a single Cast

Encoding

Location values will be encoded as Geo URIs, with latitude and longitude rounded to two decimal places, followed by an optional place label. For example, the Geo URI for Brooklyn (near Brooklyn Bridge Park) would be:

geo:40.70,-74.00;label=Brooklyn%20Bridge%20Park

This format includes:

• Latitude and longitude rounded to 2 decimal places
• A URL-encoded place label (optional)

The 2dp rounding provides an approximate precision of 1.1 kilometers, offering a good balance between usability and privacy.

Message Definitions

We'll update the existing messages to support Geo URIs:

message CastAddBody {
  repeated string embeds_deprecated = 1;  // Deprecated embeds field
  repeated uint64 mentions = 2;           // User fids mentioned in the text
  oneof parent {                          // Optional parent of the cast
    CastId parent_cast_id = 3;
    string parent_url = 7;                // Parent URL
  };
  string text = 4;                        // Text of the cast
  repeated uint32 mentions_positions = 5; // Byte positions of the mentions in the text
  repeated Embed embeds = 6;              // URIs, CastIds, or Geo URIs embedded in the cast
}

message CastRemoveBody {
  bytes target_hash = 1;                  // Message.hash value of the cast being removed
}

message CastId {
  uint64 fid = 1;                         // Fid of the cast's author
  bytes hash = 2;                         // Message.hash value of the cast
}

message Embed {
  oneof embed {
    string url = 1;
    CastId cast_id = 2;
    string geo_uri = 3;                   // New field for Geo URI
  }
}

Multiple Locations

A Cast can include multiple Geo URI embeds. This allows users to represent routes, areas, or multiple points of interest in a single Cast. Clients should be prepared to handle and display multiple locations appropriately.

Validation Rules

1. Each Geo URI in an Embed must pass the following validation rules:

• Must be a valid Geo URI format: geo:latitude,longitude;label=place_name
• Latitude must be a valid number between -90 and 90
• Longitude must be a valid number between -180 and 180

2. Both latitude and longitude must be rounded to 2 decimal places
3. The label parameter may be present and URL-encoded

A Cast may contain multiple Embed objects with Geo URIs
The total number of Embed objects (including all types) in a Cast should not exceed 2 to maintain existing expectations for Embed elements.

Rationale

Why use Geo URIs?

Geo URIs provide a standardized, concise, and documented format for representing geographic locations. They are easy to parse and can be used directly in many mapping applications and services.

Why round the latitude/longitude values to 2 decimal places?

Rounding to two decimal places provides a good balance between usability and privacy. It offers precision to about 1.1 kilometers, which is sufficient for most use cases while still protecting users from inadvertently sharing their exact location.

Why allow multiple locations in a single Cast?

Allowing multiple locations in a Cast enables users to share more complex spatial information, such as:

• Start and end points of a journey
• Multiple stops on a trip
• Comparisons between different locations

This flexibility allows for richer location-based content and features in Farcaster clients.

Backwards Compatibility

This change is backwards compatible. Older clients that don't support the new Geo URI embed type can simply ignore it, continuing to process url and cast_id embeds as before.

Reference Implementation

Here's a TypeScript implementation for creating and processing Geo URI embeds:

type Embed = {
  url?: string;
  cast_id?: { fid: number; hash: Uint8Array };
  geo_uri?: string;
};

function createGeoUriEmbed(lat: number, lon: number, label?: string): Embed {
  const roundToTwoDecimal = (num: number) => Math.round(num * 100) / 100;
  let geoUri = `geo:${roundToTwoDecimal(lat)},${roundToTwoDecimal(lon)}`;
  
  if (label) {
    const encodedLabel = encodeURIComponent(label);
    geoUri += `;label=${encodedLabel}`;
  }
  
  return {
    geo_uri: geoUri
  };
}

function processEmbeds(embeds: Embed[]): void {
  if (embeds.length > 2) {
    console.error("Error: Embed length cannot exceed 2");
    return;
  }

  embeds.forEach((embed, index) => {
    console.log(`Embed ${index + 1}:`);
    if ('url' in embed && embed.url) {
      console.log(`  URL: ${embed.url}`);
    } else if ('cast_id' in embed && embed.cast_id) {
      console.log(`  Cast ID: fid=${embed.cast_id.fid}, hash=${Buffer.from(embed.cast_id.hash).toString('hex')}`);
    } else if ('geo_uri' in embed && embed.geo_uri) {
      console.log(`  Location: ${embed.geo_uri}`);
      const { lat, lon, label } = parseGeoUri(embed.geo_uri);
      console.log(`    Latitude: ${lat}, Longitude: ${lon}${label ? `, Label: ${label}` : ''}`);
    }
  });
}

function validateGeoUri(geoUri: string): boolean {
  const geoRegex = /^geo:(-?\d{1,2}\.\d{2}),(-?\d{1,3}\.\d{2})(?:;label=.+)?$/;
  const match = geoUri.match(geoRegex);
  
  if (!match) return false;
  
  const lat = parseFloat(match[1]);
  const lon = parseFloat(match[2]);
  
  return (
    lat >= -90 && lat <= 90 &&
    lon >= -180 && lon <= 180
  );
}

function parseGeoUri(geoUri: string): { lat: number; lon: number; label?: string } {
  const [coords, labelParam] = geoUri.split(';');
  const [, latStr, lonStr] = coords.split(':')[1].split(',');
  const lat = parseFloat(latStr);
  const lon = parseFloat(lonStr);
  let label: string | undefined;
  
  if (labelParam) {
    label = decodeURIComponent(labelParam.split('=')[1]);
  }

  return { lat, lon, label };
}

// Example usage
const embeds: Embed[] = [
  { url: "https://img.uno.fun/KLf0u3MQf9.png" }, // Image URL
  createGeoUriEmbed(40.70, -74.00, "Brooklyn Bridge Park"), // Geo URI for Brooklyn (near Brooklyn Bridge Park)
];

processEmbeds(embeds);

Security Considerations

1. Privacy: The 2dp rounding of coordinates helps protect user privacy by preventing the sharing of exact locations while still providing useful precision.
2. Data Validation: Implementations must ensure that Geo URIs are properly formatted and contain valid latitude and longitude values to prevent potential exploits.

Copyright

Copyright and related rights waived via CC0.

Credits

@zachterrell57 @vrypan, @aditiharini @goksu for #196

[zachterrell57]

Generally supportive! A couple thoughts:

• Sticking this in embeds seems right
• The implementation should follow whichever method FIP: Location in user profiles #196 goes with (Encoded Lat/Long vs. Geo URI). Having two different formats of geo on the protocol would be really confusing

I still think one decimal point of precision isn't precise enough. For all the points you bring up in the "Why allow multiple locations in a single Cast?" section:

Start and end points of a journey
Multiple stops on a trip
Area boundaries (by specifying corner points)
Comparisons between different locations

These are all not really possible with an 11km margin of error

[christopherwxyz]

1. Agreed we should follow the same type as USER_DATA_LOCATION.

2. All fair points. These hold true with less uncertainty, but I will adjust the FIP if opinions favor 1dp.

[varunsrin]

I'm a fan of this proposal, wanted to add some feedback:

1. the examples in the problem section make sense for profile level location, but aren't the best use cases for cast level location. i think using your app is a better example that illustrates why cast level location is good (add location when sharing stories with friends)

2. we are considering changing FIP: Location in user profiles #196 to 2dp precision since after testing we found that 1dp caused issues with some locations.

3. requiring the "uncertainity" parameter seems unnecessary, its just implicit in the length of the lat/long. is there any value to encoding this separately?

4. one more radical approach is to not require a protocol change and just put this in the URL (which maybe should be renamed to URI) and then clients can just parse the URI and handle appropriately. it does mean that we wouldn't do any protocol level validations on length. i have to think more on whether this is the right approach.

Abuse Prevention: Clients should implement measures to prevent abuse, such as limiting the number of Geo URI embeds per Cast to 2.

the number of embeds is limited to 2 at the protocol level

[stephancill]

Agree with 4

Perhaps related to #171

[christopherwxyz]

1. Updated.
2. Updated. In my example for Brooklyn Bridge Park, we have 2dp precision, but the exact location without uncertainty is in the water off the end of the pier.
3. Removed. Originally I intended for the uncertainty to be a clear, historical marker so that clients are able to understand the difference between an exact location and an uncertain one. For example, 40.70,-74.00 is Brooklyn Bridge Park with a label, but equally so is 40.7,-74.0 even with 11km uncertainty. From RFC 5870:

Location Uncertainty

The 'u' ("uncertainty") parameter indicates the amount of uncertainty
in the location as a value in meters. Where a 'geo' URI is used to
identify the location of a particular object, indicates the
uncertainty with which the identified location of the subject is
known.

[PirosB3]

If this leads to a protocol change, will it still be backwards compatible? Can things keep working without needing to recompile gRPC, or would that require a recompile?

[christopherwxyz]

it should be backwards compatible — it’s adding a new element type to the embeds array

[aditiharini]

@christopherwxyz do you think there's value in supporting the full geo uri spec? We do need latitude and longitude of course, but I'm trying to understand whether all the other parameters supported by the geo uri spec are valuable.

If we support the full geo-uri spec, then hubs will need to perform some sort of validation on the uri data to make sure that it's reasonable and then parse out the lat, long data to make sure the precision is correct. Clients will also need to do the parsing. Trying to reason about whether using geo uri is worth this overhead or whether we should (1) only support enough of the geo uri spec to specify latitude and longitude (2) pursue a different representation (still a string) but not geo uri.

We did also think about using JSON or protobuf. The main issue with JSON is that it's not compact. Encoding lat/long directly in the proto is feasible. It doesn't save us space over the geo uri representation that contains just latitude and longitude and it does complicate the UserDataBody, but it does eliminate some of the parsing overhead. Neither of these options were particularly appealing.

You did mention that geo URI is widely supported. If that's the case, some of these concerns are moot. Are there good libraries for parsing geo URIs? Alternatively are there location apis (e.g. google places, mapbox) that directly accept geo URI?

[christopherwxyz]

I am unsure if the full specification is worth chasing compared to simple lat/long/label at the moment. The full expanse could be a iterative FIP on expanded parameters to the URI, such as adding altitude. Downscoping to just the listed parameters allows us to clearly ship a location feature with an option for more.

Pursuing a different representation could cause us to stumble into becoming geo encoding experts, or requiring more analysis for a new data pattern, which slows shipping. As a matter of principle, I prefer the simplicity of treating everything like a URI or a hash within a cast message. Converting the existing URL to URI will open up a larger surface area for consideration (and even security concerns).

Google Maps and Google Earth both have good developer examples for generating URIs. Additionally, clicking on a geo URI will natively route the user to Google Earth (or Warpcast/any other location app if it supports the URI scheme!) if the app supports it on devices or desktop. I was also able to just copy and paste the geo URI into Apple Maps and open up the location. This StackOverflow comment mentions native support via Apple Maps: https://stackoverflow.com/questions/11747570/geo-protocol-on-iphone-safari#comment136028525_11748521

[aditiharini]

Awesome, agreed on all fronts. I think shipping geo URI with just lat, long, description is reasonable and good to know that Google Earth supports this format.

[christopherwxyz]

I did a bit more digging to understand the app support. It seems like apps register their own scheme (since they want control over the link), and disfavor but still support the geo URI. I changed the FIP language from “widely supported” to “documented.”

For example, Apple Maps supports geo: but favors maps:// — Google prefers comgooglemaps://

Clients can swap the geo scheme to match their favorite map client, e.g. comgooglemaps://?center=40.76,-73.97

https://developers.google.com/maps/documentation/urls/ios-urlscheme

[vrypan]

If we modify the protocol to add a new embed_type, I suggest we revisit #171 (External Data FIP).

The original version of the FIP had a new embed type (let's call it extended data), that linked to a json, that could be used for any type of data, from long casts, to location data, to events, reviews, etc. I believe that instead of adding one new embed type every time we need it, we should go for a more generic solution.

[vrypan]

1. They can. They will have to check the HTTP headers to decide what the link corresponds to, which is expensive, or read the whole piece of data, not knowing in advance how big it is or what it is, and inspect the contents to decide if it is a json, an image, a css or a frame. It also prohibits this piece of data to be stored on things like IPFS that don't have HTTP headers. But if we can change the protocol to have a new embed type, the process can be streamlined.
2. Can't argue with belief systems :-)
3. The difference is that the first one is not stored in hubs (x 8000 copies) while the second one is.

[christopherwxyz]

1. If this data is stored on someone else's servers, how does that further the mission? Free flow of user data is imperative to lego blocks within hub and chain space.
2. Thank you haha.
3. See point one.

[vrypan]

If this data is stored on someone else's servers, how does that further the mission? Free flow of user data is imperative to lego blocks within hub and chain space.

This touches an other philosophical question: How much of the network's info must be stored on hubs? My answer is the bare minimum, with pointers to external sources (PFPs and frames work like this for example). Standardizing these external resources makes them part of the protocol (see frames) and "farcaster-compatible". I like approaches that let clients extend the protocol, without requiring updates to hub code. Ideally, I would like the core protocol (hubs) to be more HTTP and less HTML.

In this context, special treatment of specific content types (today it's location, tomorrow it may be event dates, languages, etc.) is something that should be left to clients, and we just have to make it easy and efficient.

Of course this is not an answer, we may very well decide that the best approach is to store location data on hubs. Just sharing my pov.

[varunsrin]

my view is that we should:

1. keep types as narrow as possible, and focus on maximizing client support. i'd rather have one new type (location) that all clients support than a hundred types that are fragmented across clients.

2. keep data on hubs as much as possible. federation is the abdication of the protocol's responsibility to make it easy for developers to find out the state of a piece of data. it is necessary in some cases (see mini apps) but must be avoided wherever possible.

[vrypan]

Of course this is a discussion greater than the FIP scope, but... I love it.

RSS was great, but it died for various historic reasons. RSS had well-defined types: title, description, date, author, post, etc..
The only industry that still uses RSS is podcasting. It was built on top of the one RSS element that was not narrow-scoped, the enclosure.

I would like to see an extendable, enclosure-type, property for casts. The "external data FIP" was an attempt to introduce something like it, without triggering the "we are skeptical of ossifying things in the protocol before they prove their value" reflexes of the MM team. I would have designed it better (as a new struct) if I did not have this constraint in mind. BTW, I agree with them, but in this case I'm convinced of the value.

To bring the discussion back to the specific FIP. If we agree to add a new, narrow-scoped embed type for location, I'm fine. If we use it as an opportunity to define a generic embed type that will allow one client to extend its use in ways that do not break other clients (what the current embed_url can't offer), I'm even more fine :-)

[christopherwxyz]

@aditiharini, since the image upload is not working on Warpcast, i wanted to share a mockup of implementing and not implementing label as a parameter for the geo uri.

i am fine with dropping label from this FIP if it means we move faster, but would like to see an improvement to implement. the main benefit to adding a label is that users and clients can give greater specificity over their place and location than just the coordinates.

1. clients can decide to lean on the lat/lon for place and location and decline to use the label.
2. but they also can use the label and not render or call place details from an API
3. high agency model for the network which means users can personalize their place and create new ones. i expect some support for NFT hashes at some point, as it means we move more global state and place data onchain and from behind meter APIs.