Live geolocation

Telegram allows sending the live geolocation of a user in a chat, optionally setting a proximity alert.

Sending live locations

inputGeoPointEmpty#e4c123d6 = InputGeoPoint;

inputGeoPoint#48222faf flags:# lat:double long:double accuracy_radius:flags.0?int = InputGeoPoint;

inputMediaGeoLive#971fa843 flags:# stopped:flags.0?true geo_point:InputGeoPoint heading:flags.2?int period:flags.1?int proximity_notification_radius:flags.3?int = InputMedia;

---functions---

messages.sendMedia#7852834e flags:# silent:flags.5?true background:flags.6?true clear_draft:flags.7?true noforwards:flags.14?true update_stickersets_order:flags.15?true invert_media:flags.16?true peer:InputPeer reply_to:flags.0?InputReplyTo media:InputMedia message:string random_id:long reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector<MessageEntity> schedule_date:flags.10?int send_as:flags.13?InputPeer quick_reply_shortcut:flags.17?InputQuickReplyShortcut effect:flags.18?long = Updates;

messages.editMessage#dfd14005 flags:# no_webpage:flags.1?true invert_media:flags.16?true peer:InputPeer id:int message:flags.11?string media:flags.14?InputMedia reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector<MessageEntity> schedule_date:flags.15?int quick_reply_shortcut_id:flags.17?int = Updates;

To send a live geolocation, use messages.sendMedia with an inputMediaGeoLive media .

The inputMediaGeoLive allows sending the geolocation as an inputGeoPoint with floating point latitude and longitude, with an optional accuracy_radius in meters.
Clients can also provide a heading, a direction in degrees (1-360) that can be used to indicate the direction of the user, a validity period for the current location, and a proximity_notification_radius .

The sent geolocation should be updated periodically using messages.editMessage at most every period seconds, in order to implement the "live" part of live geolocations.

To stop sharing the location, pass inputGeoPointEmpty as location and set the stopped flag to true in a last messages.editMessage call.

Receiving live locations

geoPoint#b2a2f663 flags:# long:double lat:double access_hash:long accuracy_radius:flags.0?int = GeoPoint;
messageMediaGeoLive#b940c666 flags:# geo:GeoPoint heading:flags.0?int period:int proximity_notification_radius:flags.1?int = MessageMedia;

updateGeoLiveViewed#871fb939 peer:Peer msg_id:int = Update;

Clients will receive a message with a messageMediaGeoLive, containing the information passed by the sender; when the geolocation message is marked as read, an updateGeoLiveViewed is generated.

Periodically, the geolocation will be updated with updateEditMessage/updateEditChannelMessage updates.

Live location previews

inputWebFileGeoPointLocation#9f2221c9 geo_point:InputGeoPoint access_hash:long w:int h:int zoom:int scale:int = InputWebFileLocation;

inputGeoPoint#48222faf flags:# lat:double long:double accuracy_radius:flags.0?int = InputGeoPoint;

---functions---

upload.getWebFile#24e6818d location:InputWebFileLocation offset:int limit:int = upload.WebFile;

A map preview can be generated by passing the received geoPoint to upload.getWebFile, to download an image preview of the map.

  • geo_point is generated from the lat , long accuracy_radius parameters of the geoPoint
  • access_hash is the access hash of the geoPoint
  • w - Map width in pixels before applying scale; 16-1024
  • h - Map height in pixels before applying scale; 16-1024
  • zoom - Map zoom level; 13-20
  • scale - Map scale; 1-3

The image is then downloaded as specified here ยป

Proximity alert

messageActionGeoProximityReached#98e0d697 from_id:Peer to_id:Peer distance:int = MessageAction;

messageService#2b085862 flags:# out:flags.1?true mentioned:flags.4?true media_unread:flags.5?true silent:flags.13?true post:flags.14?true legacy:flags.19?true id:int from_id:flags.8?Peer peer_id:Peer reply_to:flags.3?MessageReplyHeader date:int action:MessageAction ttl_period:flags.25?int = Message;

If:

  • A user sets a proximity_notification_radius when sending a location
  • Multiple users share their location within the same chat
  • One of the other users comes within proximity_notification_radius meters of the first user, and updates their location accordingly

An updateNewMessage/updateNewChannelMessage is generated for all chat members, containing a messageService with action messageActionGeoProximityReached:

  • messageActionGeoProximityReached.to_id is the peer that enabled proximity alerts
  • messageActionGeoProximityReached.from_id is the peer that is now in proximity of messageActionGeoProximityReached.to_id
  • messageActionGeoProximityReached.distance is the distance between them, in meters