Pathline Data API

1. How it works

Pathline publishes a ContentProvider at the authority net.extrawdw.apps.locationhistory.provider. You query one of three collections by passing a time window as URI query parameters and read the results from the returned Cursor.

The data model

Pathline organizes location data into three layers, from raw to derived:

• Samples — the raw, individual location fixes (a fused/GPS point with a timestamp, plus accuracy, speed, bearing, device state, …). The lowest level.
• Visits — stays: a continuous period spent at one place, derived by clustering samples. Carries a centroid, radius, and (when known) the matched place.
• Trips — the movements between stays, each with an inferred transport mode, a distance, and — for authorized callers — the route travelled.

Together, visits and trips form the user's timeline; samples are the raw layer beneath it. A trip references the visits it connects via from_visit_id / to_visit_id, so you can stitch a continuous stay → move → stay timeline. Pick the layer your feature needs: the timeline for a human-readable history, samples for raw analysis.

Collections

Before any of this, your app must hold the install-time API gate permission net.extrawdw.apps.locationhistory.permission.API — declare it with <uses-permission> and the system auto-grants it (no prompt). An app that doesn't declare it can't even resolve the provider, let alone query it. It's necessary but not sufficient: every read still needs the relevant runtime permission(s) below.

Two refinements layer on top of the base permission (see §4):

• Older than 30 days additionally requires READ_EXTENDED_HISTORY.
• A trip's encoded_polyline (its precise route) is gated separately from the rest of the trip row: it is populated only when the caller also holds READ_TIMELINE_ROUTE or READ_LOCATION_HISTORY, and is null otherwise. A READ_TIMELINE-only caller still gets every trip, just without its route geometry.

2. Requirements & compatibility

Package visibility (Android 11+)

Add this to your consumer app's AndroidManifest.xml, as a direct child of <manifest>, so your app can resolve Pathline's provider and permissions:

<queries>
    <package android:name="net.extrawdw.apps.locationhistory" />
</queries>

Detecting whether Pathline is installed

fun isPathlineInstalled(context: Context): Boolean =
    runCatching {
        context.packageManager.getPackageInfo("net.extrawdw.apps.locationhistory", 0)
        true
    }.getOrDefault(false)

3. Quick start

1. Declare the scopes you need and the <queries> entry in your manifest (§4).
2. Request the matching runtime permission(s) before reading (§4).
3. Query the collection for a time window and read the Cursor off the main thread (§5).

4. Permissions

The API gate (install-time)

One permission stands apart from the rest:

Just declare it with <uses-permission>; the system grants it at install with no runtime prompt and nothing to request in code. It is a coarse "this app uses the Pathline API" marker — necessary but not sufficient: every read still requires the relevant runtime permission(s) below. An app that doesn't declare it can't resolve or query the provider, and a query without it throws SecurityException.

The data permissions (runtime)

These four are all protectionLevel="dangerous" (runtime, user-approved):

A consumer must both declare a permission (manifest) and request it (runtime). Declaring without requesting, or requesting without declaring, will not grant access.

Choosing your scopes

These permissions form an escalating ladder — request the lowest tier your feature needs:

Declare (consumer AndroidManifest.xml)

<!-- Required by every consumer: the install-time gate to reach the provider (auto-granted). -->
<uses-permission android:name="net.extrawdw.apps.locationhistory.permission.API" />

<uses-permission android:name="net.extrawdw.apps.locationhistory.permission.READ_TIMELINE" />
<!-- Only if you draw trip routes (or skip it and rely on READ_LOCATION_HISTORY): -->
<uses-permission android:name="net.extrawdw.apps.locationhistory.permission.READ_TIMELINE_ROUTE" />
<!-- Only if you need raw location samples: -->
<uses-permission android:name="net.extrawdw.apps.locationhistory.permission.READ_LOCATION_HISTORY" />
<!-- Only if you need data older than 30 days: -->
<uses-permission android:name="net.extrawdw.apps.locationhistory.permission.READ_EXTENDED_HISTORY" />

Request at runtime

val launcher = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { result ->
    val granted = result.values.all { it }
    // Reload your data if granted; otherwise guide the user (see the OEM note below).
}

// Request only what the current feature needs:
launcher.launch(arrayOf(
    "net.extrawdw.apps.locationhistory.permission.READ_TIMELINE",
))

The user can revoke any of these at any time in Settings → Apps → (your app) → Permissions.

Permission requests may not work on every device

fun openAppSettings(context: Context) {
    context.startActivity(
        Intent(
            Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
            Uri.fromParts("package", context.packageName, null),
        ).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
    )
}

Errors

5. Querying

Every collection is queried by a time window passed as URI query parameters:

content://net.extrawdw.apps.locationhistory.provider/<collection>?start=<epochMs>&end=<epochMs>

Grouping batched reads

A single user-facing refresh often reads several collections at once (e.g. visits + trips + samples). By default those log as separate entries in Pathline's access manager. Pass an optional group key — the same value on every request in the batch — to have Pathline display them as one expandable access group.

• Value: a wall-clock epoch-ms number at/near "now" — use System.currentTimeMillis() captured once at the start of the batch and reused. (Not elapsedRealtime.)
• Validity: honored only when it lands essentially at "now" — between ~120 s before and a few seconds after the moment Pathline receives the request; stale, far-future, or non-numeric values are ignored (the read is still logged, just ungrouped). An invalid group never causes an error.
• Scope: grouping is per calling package — you can only group your own reads, never merge with another app's.
• Display only: group has zero effect on what data a query returns. It also can't hide reads — Pathline still logs every individual request; grouped entries are expandable to the originals, and every request (with its group key) appears in the user's exportable log.

val batch = System.currentTimeMillis()           // one value for the whole refresh
val visits  = query("visits",  start, now, group = batch)
val trips   = query("trips",   start, now, group = batch)
val samples = query("samples", start, now, group = batch)

Match semantics

• Timeline (visits, trips) — overlap. Any item whose [start_ms, end_ms] span intersects the requested [start, end) window is returned in full, including items that began before start or end after end. A request that lands in the middle of a stay or a journey returns that whole item — you never get truncated fragments.
• Samples — point-in-window. A sample is returned when start <= timestamp_ms < end.

Ordering

Results are ordered ascending by start_ms (timeline) / timestamp_ms (samples).

Ignored arguments

Paging

6. Data reference

All times are epoch milliseconds, UTC. Nullable columns are marked ?. Each collection also advertises a directory MIME type via getType() — vnd.android.cursor.dir/vnd.net.extrawdw.apps.locationhistory.<visit|trip|sample> — though ContentResolver.query never requires you to read it.

visits

trips

samples

Enumerations

String columns use fixed, stable token sets. Treat any unrecognized value as the UNKNOWN/null case.

7. Complete example

A minimal, production-shaped read: declare → request (with OEM fallback) → query off the main thread.

object Pathline {
    const val AUTHORITY = "net.extrawdw.apps.locationhistory.provider"
    const val READ_TIMELINE = "net.extrawdw.apps.locationhistory.permission.READ_TIMELINE"

    fun windowUri(collection: String, startMs: Long, endMs: Long): Uri =
        Uri.parse("content://$AUTHORITY/$collection").buildUpon()
            .appendQueryParameter("start", startMs.toString())
            .appendQueryParameter("end", endMs.toString())
            .build()
}

data class Visit(val id: Long, val name: String?, val startMs: Long, val endMs: Long)

/** Reads visits overlapping [startMs, endMs). Call from a background dispatcher. */
fun readVisits(resolver: ContentResolver, startMs: Long, endMs: Long): List<Visit> {
    val out = ArrayList<Visit>()
    resolver.query(Pathline.windowUri("visits", startMs, endMs), null, null, null, null)?.use { c ->
        val id = c.getColumnIndexOrThrow("_id")
        val name = c.getColumnIndexOrThrow("place_name")
        val start = c.getColumnIndexOrThrow("start_ms")
        val end = c.getColumnIndexOrThrow("end_ms")
        while (c.moveToNext()) {
            out += Visit(
                id = c.getLong(id),
                name = if (c.isNull(name)) null else c.getString(name),
                startMs = c.getLong(start),
                endMs = c.getLong(end),
            )
        }
    }
    return out
}

Driving it from a screen, with the permission flow and the OEM fallback:

private val needed = arrayOf(Pathline.READ_TIMELINE)

private val permissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { if (it.values.all { granted -> granted }) loadTimeline() else /* show "Open settings" hint */ }

private fun ensureAccessThenLoad() {
    val missing = needed.filter {
        ContextCompat.checkSelfPermission(this, it) != PackageManager.PERMISSION_GRANTED
    }
    if (missing.isEmpty()) loadTimeline() else permissionLauncher.launch(missing.toTypedArray())
}

private fun loadTimeline() {
    lifecycleScope.launch(Dispatchers.IO) {
        val now = System.currentTimeMillis()
        val visits = try {
            readVisits(contentResolver, now - 24 * 60 * 60 * 1000L, now)
        } catch (e: SecurityException) {
            emptyList() // permission missing/revoked — prompt or deep-link to settings
        }
        withContext(Dispatchers.Main) { render(visits) }
    }
}

8. Best practices

fun canRead(context: Context, vararg permissions: String): Boolean =
    permissions.all {
        ContextCompat.checkSelfPermission(context, it) == PackageManager.PERMISSION_GRANTED
    }

// Guard, don't probe:
if (canRead(context, Pathline.READ_TIMELINE)) {
    readVisits(contentResolver, start, now)   // safe — permission held
} else {
    requestPermissions(arrayOf(Pathline.READ_TIMELINE))  // ask first
}

• Query in bounded windows. Prefer a day or a week per query, especially for samples. There is no paging.
• Always go off-thread. query is blocking IPC; use a background dispatcher / WorkManager.
• Resolve columns by name. Use getColumnIndexOrThrow and handle nullables with Cursor.isNull.
• Request the narrowest scope. Only ask for READ_EXTENDED_HISTORY when the user actually navigates past 30 days.
• Handle absence and revocation gracefully. Pathline may be uninstalled, or a permission revoked, between launches — catch SecurityException and re-check on resume.
• Don't hardcode column indices or assume ordering beyond the documented ascending sort.

9. Privacy & transparency

Pathline treats third-party access as a first-class privacy surface: every interaction is recorded on-device and shown to the user, who can revoke any app at any time. Design your integration assuming the user sees exactly what you do.

• Read the minimum, on demand. Request the narrowest scope, over the smallest window, in clear response to a user action — bursty or unexplained access is visible to the user.
• On-device only. The audit metadata never leaves the device and is not included in Pathline's encrypted backups.
• Your data handling is your responsibility. This API never exposes another user's data and never leaves the device by itself; what your app does with what it reads is on you (and subject to Google Play's policies).

Notification behavior

Pathline proactively alerts the user about third-party access. Assume both of the following will surface as user notifications:

• On a successful read — a separate, per-app notification (your app's icon on the right, Pathline's on the left) naming your app and summarizing what was read (e.g. "Acme accessed 6 visits, 2,636 location samples."). Reads are coalesced (a burst becomes one alert) and rate-limited per app with an escalating back-off (next alert waits ~1h, then 2h, 4h … up to 24h), so a frequently-reading app won't spam the user. The back-off resets after ~48h quiet.
• On a denied attempt — a separate, immediate notification ("Acme tried to access Location history without permission."). It fires without the coalescing delay because a blocked access is a security-relevant event the user should hear about right away. It rides its own per-app back-off lane (so it never displaces, or is muffled by, the read alert) with the same escalating limit for repeats.
• Standing-access reminder — periodically (about weekly), Pathline reminds the user which apps still hold access, so a granted-and-forgotten app is surfaced for review.

All of these use a dedicated, default-importance "Data access alerts" notification channel the user can tune or mute in system settings, and deep-link into Settings → Access to Pathline data. The user can reset all back-off timers from there, so the next access (read or denied) alerts again at once.

10. Stability & versioning

The following are part of the stable contract for API revision 1 and will not change without a new API revision:

• The authority net.extrawdw.apps.locationhistory.provider.
• The collection paths visits, trips, samples.
• The permission names — including the install-time gate …permission.API — the query-parameter names (start, end), and the column names in §6.

11. Troubleshooting

Appendix A — Contract constants

Pathline ships the canonical, dependency-free contract at net.extrawdw.apps.locationhistory.api.PathlineContract — prefer copying that file verbatim to avoid string literals. The excerpt below is the string-constant subset for quick reference; the shipped file additionally provides a typed CONTENT_URI and CONTENT_TYPE per collection and a COLUMNS array for each.

Download PathlineContract.kt (revision 1)

object PathlineContract {
    const val AUTHORITY = "net.extrawdw.apps.locationhistory.provider"

    /** Windows reaching further back than this need READ_EXTENDED_HISTORY. */
    const val EXTENDED_HISTORY_WINDOW_MS = 30L * 24 * 60 * 60 * 1000

    object Permissions {
        /** Install-time gate (normal); declare to reach the provider. Necessary, not sufficient. */
        const val API = "net.extrawdw.apps.locationhistory.permission.API"
        const val READ_TIMELINE = "net.extrawdw.apps.locationhistory.permission.READ_TIMELINE"
        const val READ_TIMELINE_ROUTE = "net.extrawdw.apps.locationhistory.permission.READ_TIMELINE_ROUTE"
        const val READ_LOCATION_HISTORY = "net.extrawdw.apps.locationhistory.permission.READ_LOCATION_HISTORY"
        const val READ_EXTENDED_HISTORY = "net.extrawdw.apps.locationhistory.permission.READ_EXTENDED_HISTORY"
    }

    object QueryParams {
        const val START = "start" // inclusive, epoch ms (required)
        const val END = "end"     // exclusive, epoch ms (optional, defaults to now)
        const val GROUP = "group" // optional batch key: epoch ms ~now, within 120s of receipt
    }

    object Visits {
        const val PATH = "visits"
        const val ID = "_id"
        const val START_MS = "start_ms"
        const val END_MS = "end_ms"
        const val PLACE_ID = "place_id"
        const val PLACE_NAME = "place_name"
        const val LATITUDE = "latitude"
        const val LONGITUDE = "longitude"
        const val RADIUS_METERS = "radius_meters"
        const val CONFIDENCE = "confidence"
        const val CONFIRMED = "confirmed"
        const val IS_ONGOING = "is_ongoing"
    }

    object Trips {
        const val PATH = "trips"
        const val ID = "_id"
        const val START_MS = "start_ms"
        const val END_MS = "end_ms"
        const val MODE = "mode"
        const val MODE_CONFIDENCE = "mode_confidence"
        const val DISTANCE_METERS = "distance_meters"
        const val ENCODED_POLYLINE = "encoded_polyline"
        const val CONFIRMED = "confirmed"
        const val FROM_VISIT_ID = "from_visit_id"
        const val TO_VISIT_ID = "to_visit_id"
    }

    object Samples {
        const val PATH = "samples"
        const val ID = "_id"
        const val TIMESTAMP_MS = "timestamp_ms"
        const val LATITUDE = "latitude"
        const val LONGITUDE = "longitude"
        const val ALTITUDE = "altitude"
        const val ACCURACY = "accuracy"
        const val BEARING = "bearing"
        const val SPEED = "speed"
        const val PROVIDER = "provider"
        const val IS_MOCK = "is_mock"
        const val DEVICE_STATE = "device_state"
        const val AR_ACTIVITY = "ar_activity"
        const val NETWORK_TRANSPORT = "network_transport"
        const val INCLUDED_IN_COMPUTATION = "included_in_computation"
    }
}