Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/photon-hq/advanced-imessage-kit/llms.txt

Use this file to discover all available pages before exploring further.

refreshFindMyFriends()

Refreshes and returns the latest Find My location data for all friends who are sharing their location with you.
const locations = await sdk.icloud.refreshFindMyFriends();

Returns

locations
FindMyLocationItem[]
An array of location items for all friends sharing their location

FindMyLocationItem

Represents location data for a friend in the Find My network.

Fields

handle
string | null
The phone number or email address of the person sharing their locationExample: "+1234567890"
coordinates
[number, number]
A tuple containing [latitude, longitude] coordinatesExample: [37.7749, -122.4194]
long_address
string | null
Full address of the locationExample: "123 Main St, San Francisco, CA 94102, USA"
short_address
string | null
Shortened address of the locationExample: "123 Main St"
subtitle
string | null
Additional location context or description
title
string | null
Location name or labelExample: "Home" or "Work"
last_updated
number
Unix timestamp (in milliseconds) when the location was last updatedExample: 1709438400000
is_locating_in_progress
0 | 1 | boolean
Whether a location refresh is currently in progress
status
'legacy' | 'live' | 'shallow'
The quality/type of location data:
  • legacy: Older location data
  • live: Real-time location tracking
  • shallow: Basic location data
expiry
number | null
default:"null"
Unix timestamp (in milliseconds) when the location data expires (for live locations)Example: 1709442000000

Example

Refresh Find My data and check if a specific contact is sharing their location:
import { AdvancedIMessageKit } from '@photon-ai/advanced-imessage-kit';

const sdk = new AdvancedIMessageKit({
  serverUrl: 'http://localhost:1234',
  password: 'your-password'
});

await sdk.connect();

// Refresh and get all friend locations
const locations = await sdk.icloud.refreshFindMyFriends();

// Find a specific contact
const targetHandle = '+1234567890';
const friendLocation = locations.find(loc => loc.handle === targetHandle);

if (friendLocation) {
  const [lat, lng] = friendLocation.coordinates;
  console.log(`Friend is at: ${lat}, ${lng}`);
  console.log(`Address: ${friendLocation.long_address}`);
  
  // Create Google Maps URL
  const mapsUrl = `https://maps.google.com/?q=${lat},${lng}`;
  console.log(`View on map: ${mapsUrl}`);
  
  // Check if location expires
  if (friendLocation.expiry) {
    const minutesRemaining = Math.floor(
      (friendLocation.expiry - Date.now()) / 60000
    );
    console.log(`Location expires in ${minutesRemaining} minutes`);
  }
} else {
  console.log('Friend is not sharing location');
}

// List all friends sharing location
console.log(`\nTotal friends sharing: ${locations.length}`);
for (const loc of locations) {
  console.log(`- ${loc.handle}: ${loc.status}`);
}
  • getFindMyFriends() - Get cached location data without refreshing
  • getLocationForHandle(handle) - Get location for a specific handle
  • isHandleSharingLocation(handle) - Check if a handle is sharing their location
Location data requires iCloud to be signed in on the BlueBubbles server and Find My Friends to be enabled.

Build docs developers (and LLMs) love