Skip to main content

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