Pathline Data API

1. How it works

Pathline publishes a ContentProvider at the authority net.extrawdw.apps.locationhistory.provider. You query a collection — usually 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

The access model

Reaching Pathline's data passes through three gates, from foundation up. All three must be open for a data read to succeed; §4 is the full reference.

1. The install-time API gate — your app declares …permission.API with <uses-permission>; the system auto-grants it (no prompt). It guards the whole provider: an app that doesn't declare it can't even resolve it, and every query — including status — requires it. Necessary, but not sufficient on its own.
2. The user's access switch — one master toggle for all third-party data access (Pathline → Settings → Access to Pathline data). Defaults off; while off, every data read is denied no matter what permissions you hold. Check status first and request access if needed.
3. The runtime data permissions — READ_TIMELINE, READ_LOCATION_HISTORY, and their refinements, each user-approved per scope in the system permission dialog.

The lone exception is status: it sits behind gate 1 like everything else, but bypasses gates 2 and 3 (no switch, no runtime permission) precisely so you can probe whether to read.

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. Access & permissions

Access is layered: the install-time API gate (gate 1) is the foundation — it guards the entire provider, including status. Above it, the user access switch (gate 2) governs all data reads, and the per-scope runtime permissions (gate 3) govern which data. All three must be open for a data read. This section covers each in turn, then how to declare, request, and handle errors.

The API gate (install-time)

The foundation every other gate rests on — one permission that 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 data read still requires the relevant runtime permission(s) below. An app that doesn't declare it can't resolve or query the provider at all (the provider is exported but guarded by this permission), and any query without it throws SecurityException — there is no route, not even status, that answers without it.

The access switch

Past the API gate sits a single user-controlled access switch — Pathline → Settings → Access to Pathline data. It is the master gate (user-facing) for all third-party data access at once.

• Defaults off. The user opts in via a first-run consent screen (shown when an app first requests access) or the Settings toggle.
• While off, every data read is denied — visits, trips, samples, places, and places/<id>/visits all throw SecurityException, regardless of which runtime permissions you hold. Only status still answers (it sits behind the API gate alone).
• A switch-off denial is logged but not notified. It's recorded in the audit log (attributed to the install-time …permission.API gate) but, unlike a per-app permission denial, does not alert the user — turning the whole API off is not a per-app breach. (Contrast: a denial because your app lacks a granted permission does notify — see §9.)
• Don't fail silently. Read status (access_enabled) before querying; if it's off, prompt with the request-access action instead of letting reads throw.

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)

The places collection

visits and trips carry a place_id (and visits a convenience place_name), but the full place record — its address, category, source, and stable center — lives in the places collection. It works differently from the windowed collections:

• Not time-windowed. start / end are ignored. Query …/places for all the places you're allowed to see, or pass ids — a comma-separated list — to fetch specific ones: …/places?ids=12,40,7.
• Access-scoped. You only ever see a place after you've read a confirmed visits row that referenced it (with a permission you held). An unconfirmed visit — even one matched to a saved place — does not grant access on its own. An unfiltered query returns exactly your granted set; an ids filter is intersected with it, so ids you've never encountered are silently omitted (never an error). This means the typical flow is: read visits → collect the distinct place_ids of confirmed rows → fetch their details from places once and cache them, instead of re-reading place_name on every visit.
• Permission. READ_TIMELINE — the same scope as visits. (No window, so READ_EXTENDED_HISTORY never applies to the directory itself.)

A place's visit history

To list every visit at one place over time, query its history sub-collection: …/places/<place_id>/visits. These rows are deliberately lean — they carry no place_name/address, because the place is identified by the <place_id> in the path and you already have its details from places. This avoids re-sending the same saved-place info on every history row.

• Windowed (overlap). start is required (epoch ms); end defaults to now. Same overlap semantics as visits, and the same ascending start_ms ordering — be explicit about how far back you read.
• Extended history. A window starting more than 30 days ago requires READ_EXTENDED_HISTORY in addition to READ_TIMELINE. To read recent history with just READ_TIMELINE, pass a start within the last 30 days; to read the whole history, pass start=0 and hold READ_EXTENDED_HISTORY.
• Access-scoped. Only readable for a place you've been granted (seen on a confirmed visits row). Its history then includes all that place's visits, confirmed or not. A place you haven't been granted — or one that doesn't exist — returns no rows (indistinguishable, so you can't probe ids).

val now = System.currentTimeMillis()
// All visits at place 42 in the last 30 days (READ_TIMELINE only):
val recent = Uri.parse("content://$AUTHORITY/places/42/visits").buildUpon()
    .appendQueryParameter("start", (now - 30L*24*60*60*1000).toString()).build()
// Entire history at place 42 — start at the epoch; also needs READ_EXTENDED_HISTORY:
val all = Uri.parse("content://$AUTHORITY/places/42/visits").buildUpon()
    .appendQueryParameter("start", "0").build()

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.
• Places — not windowed (directory); Place history — overlap, like visits.

Ordering

The windowed collections are ordered ascending: visits, trips, and place history by start_ms; samples by timestamp_ms. The places directory has no guaranteed order (it's a keyed lookup, not a window) — sort it client-side if you need one, e.g. by name.

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|place|place_visit> — though ContentResolver.query never requires you to read it.

visits

trips

samples

places

Directory MIME type vnd.android.cursor.dir/vnd.net.extrawdw.apps.locationhistory.place. Returned only for places you're allowed to see, in no guaranteed order (sort client-side).

places/<id>/visits (place history)

Directory MIME type vnd.android.cursor.dir/vnd.net.extrawdw.apps.locationhistory.place_visit. Lean visit rows for one place — no place_name/address (resolve those once from places).

status

Single-row, item MIME type vnd.android.cursor.item/vnd.net.extrawdw.apps.locationhistory.status. Always answerable — not gated by the access switch, needs no runtime permission, returns no personal data, and is not logged. It does still require the install-time API gate (like every route), so a caller that declares …permission.API can always read it. Query it to decide whether to read or to prompt the user.

To know which permissions your own app holds, check them directly with ContextCompat.checkSelfPermission(...) — the provider doesn't report them.

Requesting access

When status.access_enabled is 0, launch the request-access action for a result to open Pathline's onboarding so the user can turn the API on. Pathline shows it with your app's name and icon (and a note that it's the overall switch, not specific to you), then returns you to where you were — RESULT_OK when access ends up on, RESULT_CANCELED otherwise, with the result intent carrying the boolean extra access_enabled. If access is already on it returns RESULT_OK immediately without prompting.

private val requestAccess = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) reload() // access is now on (or re-read status)
}

// PathlineContract.Actions.requestApiAccessIntent(), targeted at Pathline:
requestAccess.launch(
    Intent("net.extrawdw.apps.locationhistory.action.REQUEST_API_ACCESS")
        .setPackage("net.extrawdw.apps.locationhistory")
)

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 2 and will not change without a new API revision:

• The authority net.extrawdw.apps.locationhistory.provider.
• The collection paths visits, trips, samples, places, places/<id>/visits, and status.
• The access-switch behavior and the …action.REQUEST_API_ACCESS request action.
• The permission names — including the install-time gate …permission.API — the query-parameter names (start, end, ids), 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 2)

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, except on `places`)
        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
        const val IDS = "ids"     // optional comma-separated place-id filter for `places`
    }

    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"
    }

    object Places {
        const val PATH = "places"
        const val ID = "_id"
        const val NAME = "name"
        const val ADDRESS = "address"
        const val CATEGORY = "category"
        const val SOURCE = "source"               // USER | MAPS | INFERRED
        const val GOOGLE_PLACE_ID = "google_place_id"
        const val LATITUDE = "latitude"
        const val LONGITUDE = "longitude"
        const val RADIUS_METERS = "radius_meters"

        const val VISITS_PATH = "visits"          // content://…/places/<id>/visits
        fun visitHistoryUri(placeId: Long): Uri =
            Uri.parse("content://$AUTHORITY/$PATH/$placeId/$VISITS_PATH")

        // Lean visit-history rows (no place_name/address — resolve once from the place above).
        object VisitHistory {
            const val ID = "_id"
            const val START_MS = "start_ms"
            const val END_MS = "end_ms"
            const val PLACE_ID = "place_id"
            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 Status {
        const val PATH = "status"
        const val ACCESS_ENABLED = "access_enabled"
    }

    object Actions {
        const val REQUEST_API_ACCESS = "net.extrawdw.apps.locationhistory.action.REQUEST_API_ACCESS"
        const val EXTRA_ACCESS_ENABLED = "access_enabled" // boolean result extra
        fun requestApiAccessIntent(): Intent = Intent(REQUEST_API_ACCESS).setPackage(PACKAGE)
    }

    const val PACKAGE = "net.extrawdw.apps.locationhistory"
}