Geolocation

[zachterrell57]

Problem

The Farcaster protocol currently does not support the use of geolocation data. By integrating geolocation capabilities, the protocol will enable the creation of innovative location-based clients, improve feed targeting, and provide richer analytics.

Specification

Below are two approaches for integrating geolocation data into the Farcaster protocol, both designed to cater to different operational preferences and complexities:

Option 1: Structured Geolocation Types

This approach utilizes a defined set of types that categorize geolocation data according to its granularity. It allows for clear and consistent communication of the location detail being shared, which can facilitate easier application development and data handling on the client side.

// Geolocation data associated with a user or cast
message Geolocation {
  GeolocationType type = 1; // Type of geolocation granularity
  oneof location {
    string country = 2;     // Country name for CountryLevel granularity
    string city = 3;        // City name for CityLevel granularity
    Coordinates coords = 4; // Coordinates for GeoCoords granularity
  }
}

// Geolocation granularity types
enum GeolocationType {
  GEOLOCATION_TYPE_NONE = 0;     // Indicates no geolocation data is provided or geolocation is opted out by the user
  GEOLOCATION_TYPE_COUNTRY = 1;  // Country-level granularity for general location without precise coordinates
  GEOLOCATION_TYPE_CITY = 2;     // City-level granularity for general location without precise coordinates
  GEOLOCATION_TYPE_COORDS = 3;   // Exact coordinates for specific location details
}

// Structure for storing latitude and longitude
message Coordinates {
  double latitude = 1;  // Latitude of the location, range: -90.00000 to 90.00000
  double longitude = 2; // Longitude of the location, range: -180.00000 to 180.00000
}

Where latitude and longitude are numbers of up to 5 decimal places, [which will give ~1m of precision](https://en.wikipedia.org/wiki/Decimal_degrees)

Option 2: Simple String Field

An alternative option is to use a single string field for geolocation. This method offers flexibility, allowing clients to determine the format and validity of the location data themselves. It simplifies the protocol but requires clients to handle the parsing and validation of the location string.

message Geolocation {
  string location = 1;  // Freeform string representing the location
}

This simpler approach avoids the overhead of managing specific types and allows for any form of location data to be entered, from country names to detailed coordinates. However, it places more responsibility on client applications to interpret and validate the data correctly.

User Data

Add a new USER_DATA_TYPE_LOCATION field at the empty position 7

enum UserDataType {
  ...
  USER_DATA_TYPE_LOCATION = 7; // Location
}

Where USER_DATA_TYPE_LOCATION is valid only:

• If m.data.body.type is USER_DATA_TYPE_LOCATION, value must be valid Geolocation
• If m.data.body.location is valid GeolocationType

CastAddBody

Add a new geolocation field at the empty position 8

message CastAddBody {
	...             
  Geolocation geolocation = 8;   // Geolocation where the user casted from
}

• The geolocation field is optional, reflecting that not all casts will include geolocation data. Applications should handle casts both with and without geolocation data gracefully.

Rationale

1. Enhancing User Experience and Enabling New Applications:

• Local Discovery and Event Coordination: Enables users to find content and connections based on geographic location, including local events, meetups, and gatherings.
• Innovative Location-based Services: Supports the creation of location-based check-in applications and location-gated content, along with interactive maps for exploring geotagged activities and content.

2. Content Filtering, Curation, and Recommendations:

• Geographic Relevance: Allows users to filter and curate feeds based on location, improving the relevance of content. Feed algorithms can also factor in geolocation to tailor recommendations, enhancing user engagement by presenting content and connections that are geographically relevant.

3. Enhanced Analytics and Insights:

• User Distribution and Engagement Analysis: Geolocation data offers insights into the geographic distribution of the user base and regional engagement patterns, supporting targeted content creation, marketing strategies, and platform optimization.
• Richer Dashboarding Experiences: Enables detailed visualizations of engagement and user activity, including heatmaps and regional engagement metrics.

[gregfromstl]

What about a single Coordinate field? The city and country types feel redundant since clients wanting less specific location can just "round up" to the general area any given coordinate is in. The unstructured string field is interesting but would cause too much uncertainty for clients trying to parse that field if everyone has their own way of representing location.

[MrKevinOConnell]

Yeah, I think only coordinates are needed for this - beyond that clients can decide how to parse it

[zachterrell57]

Higher abstractions of location (city, country) would be included for privacy purposes. If only coordinates are supported, users may not feel comfortable having their exact coordinates shared with every cast. Clients could do the work of converting specific coordinates to broader locations, but not sure this will meaningfully dispel privacy concerns

[gregfromstl]

Clients don't have to take a user's exact location. They can use whatever method they'd like to convert from some user-input (exact tracked location, text city input, etc) to some coordinates representing the user's area. On the receiving end clients can display these coordinates as specific as they'd like. If all geolocation data is submitted by clients, I'd argue any privacy concerns should be addressed at the client level rather than including less specific fields that clients have no requirement to respect.

[MrKevinOConnell]

Yeah from experience most operating systems are pretty strict on location usage, and tend to flag the user heavily on it, apple for example makes it so by default the exact location of a user isn't sent, but an approximation is.

Given this is completely optional and can be opted out of, i feel like having a coordinate field is the simplest way to parse this info between clients

One alternative is you could just have it be a string "location" that is entered in, kind of like how warpcast does it

[varunsrin]

Thanks for putting this together, a few thoughts:

1. Is this high priority for any clients / apps to integrate right now? If its not going to get usage, likely lower on our priority stack.

2. I think we should start adding it to user data first. Adding geo to cast data has a lot of implications for data size on the network, which we'll need to think through.

3. We should be opinionated about how geo is stored. Giving too many options (latlong vs city vs country) may result in clients having to do a lot of work to unpack data.

[zachterrell57]

1. Speaking for myself, the first thing I'd do is make some sort of dashboard with this data. I think it will be very useful to see how geographical trends change as the protocol scales. As I rewrite Farcaster.network geo data is something I'm hoping to highlight. Interface will be something similar to https://farcaster.spindl.xyz/ or https://www.starlinkmap.org/. There are also other apps that could take advantage as well. Creators of apps like Check-In Caster have expressed interest in using this as opposed to doing to geo data in a proprietary way.

2. This is reasonable, might be worth just doing a quick and dirty calculation to see approx. how much extra data it would add, but that will depend on ⬇️

3. Do you have an initial opinion? I'm leaning towards a simple string field, moving the complexity from unpacking a bunch of nesting (really annoying) to parsing to the correct format (slightly less annoying)

[PJijin]

Hey, I'm Jijin from Check-In Caster (https://www.checkincaster.xyz/)

1. We are building Foursquare on Farcaster with the feature 'Check-in and Earn'. The geo-location data is highly useful for our app as well. I believe this option enables developers/clients to build a variety of apps, such as analytics based on geo-location and sharing the location of the photos/videos they cast. etc.

2. +1

3. Sharing location details is optional, correct? In that case, can we store the latitude and longitude, which allow app developers to parse the information from that?

[vrypan]

Alternative approaches:

1. Store the location coordinates in an embed_url in the form of https://en.wikipedia.org/wiki/Geo_URI_scheme
2. Set parent_cast_url to a geo_uri.

I think the second one would be usually preferred (also allows to get all casts with a specific location as parent) and leaves both embed_url for other embeds. But ideally, clients could support both.

[zachterrell57]

This is a nice and efficient way to store geo data, but I worry that some users will prefer the obfuscation of just reporting a country or city, not their actual coordinates. Wiki article is unclear on how fuzzy you can make it. For example, if I wanted to make my geo location just "San Francisco, CA" would my geo_uri just point to the geographical center of SF? Might make the clients' work more difficult

Not sure what you mean by 2.

[vrypan]

Re 2: I was referring to FIP-2. A cast that is a reply to a URI.

My understanding is that you can use as much precision as you like in GPS coordinates. The "u" parameter is there to indicate that lack (or not) of precision. (GPS coordinates have many more uses than showing users on a map :-), and in many cases being aware of the coordinates precision can be super important.)

I could see a future where lat/lon coordinates are stored in hubs, but I think that storing location names (arbitrary length unicode strings) is not a good idea, and the way to go is with some kind of pointer to an external registry (geo URIs are an example of this, but there are airport codes, postal codes, and many other location registries designed to address different needs).

[varunsrin]

closing in favor of #196 and #197, thanks for starting the discussion @zachterrell57