Location History

@dieter/location-historyv2026.09.18.1· 18d agoMODELSREPORTS

01README

Provider-neutral location evidence, enrichment, geocoding, timeline inference, and reports.

02Models7

@dieter/location-annotationsv2026.09.18.1location_annotations.ts

Global Arguments

Argument	Type	Required	Description
annotationFile	string	yes	Private YAML file containing manual location facts and corrections.

fn import(outputChunkSize: number)

Validate and import manual location annotations

Argument	Type	Required	Description
outputChunkSize	number	yes	Annotations per NDJSON output file; changes file layout, not imported facts.

Resources

summary(infinite)— Summary of validated manual location annotations

Files

evidence(application/x-ndjson)— Generic manual location evidence as NDJSON

exclusions(application/x-ndjson)— Manual evidence exclusions as NDJSON

@dieter/location-evidencev2026.09.18.1location_evidence.ts

Global Arguments

Argument	Type	Required	Description
sources	array	yes	Generic source-adapter outputs to curate.

fn curate(outputChunkSize: number)

Merge generic adapter evidence and apply exclusions

Argument	Type	Required	Description
outputChunkSize	number	yes	Records per NDJSON output file; changes file layout, not curated evidence.

Resources

summary(infinite)— Manifest for curated generic location evidence

Files

evidence(application/x-ndjson)— Curated generic location evidence as NDJSON

audit(application/x-ndjson)— Applied and unmatched evidence-exclusion audit records

warnings(application/x-ndjson)— Unmatched evidence-exclusion warnings

@dieter/location-geocodingv2026.09.18.1location_geocoding.ts

Global Arguments

Argument	Type	Required	Description
sourceModelType	string	yes	Model type that produced recurring-place data.
sourceModelId	string	yes	ID of the model that produced recurring-place data.
placeChunkNames	array	yes	Recurring-place file names to reverse geocode.
evidenceChunkNames	array	yes	Evidence file names to enrich with cached geography.
endpoint	url	yes	Nominatim-compatible reverse-geocoding API endpoint.
userAgent	string	yes	Identifying HTTP User-Agent required by the geocoding service.
acceptLanguage	string	yes	Preferred language for returned place names.
minIntervalMs	number	yes	Minimum delay between external geocoding requests, in milliseconds.
clusterPrecision	number	yes	Decimal precision used to derive reusable geocoding-cache keys.

fn sync(maxRequests?: number)

Reverse geocode uncached coordinate clusters sequentially

Argument	Type	Required	Description
maxRequests?	number	no	Optional development limit on uncached reverse-geocoding requests; omit to complete all pending places.

fn enrich(outputChunkSize: number)

Propagate cached reverse geocodes through recurring-place evidence

Argument	Type	Required	Description
outputChunkSize	number	yes	Records per NDJSON output file; changes file layout, not enrichment results.

Resources

geocode(infinite)— Cached reverse-geocode fact

summary(infinite)— Reverse-geocoding synchronization or enrichment summary

Files

places(application/x-ndjson)— Recurring places enriched with cached location names

evidence(application/x-ndjson)— Generic location evidence enriched with named geography

@dieter/location-personal-placesv2026.09.18.1location_personal_places.ts

Global Arguments

Argument	Type	Required	Description
sourceModelType	string	yes	Model type that produced normalized location evidence.
sourceModelId	string	yes	ID of the model that produced normalized location evidence.
evidenceChunkNames	array	yes	Evidence file names to resolve against personal places.
places	array	yes	Personal-place catalog; use an empty array when no precise places are configured.

fn enrich(maxRecords?: number)

Enrich coordinate evidence from the personal-place catalog

Argument	Type	Required	Description
maxRecords?	number	no	Development-only limit on evidence records; output is truncated when reached.

Resources

summary(infinite)— Summary of local personal-place resolution

Files

evidence(application/x-ndjson)— Location evidence enriched with personal-place matches

@dieter/location-recurring-placesv2026.09.18.1location_recurring_places.ts

Global Arguments

Argument	Type	Required	Description
sourceModelType	string	yes	Model type that produced generic location evidence.
sourceModelId	string	yes	ID of the model that produced generic location evidence.
sourceChunkNames	array	yes	Generic evidence file names to cluster.

fn enrich(radiusKm: number, outputChunkSize: number)

Cluster coordinate-bearing generic evidence without a time limit

Argument	Type	Required	Description
radiusKm	number	yes	Maximum distance from a recurring-place anchor to group coordinate evidence, in kilometres.
outputChunkSize	number	yes	Records per NDJSON output file; changes file layout, not clustering results.

Resources

summary(infinite)— Recurring-place clustering summary

Files

evidence(application/x-ndjson)— Generic evidence enriched with recurring places

places(application/x-ndjson)— Recurring spatial-place representatives

@dieter/location-takeoutv2026.09.18.1location_takeout.ts

Global Arguments

Argument	Type	Required	Description
sourceDirectory	string	yes	Read-only root directory of an extracted Google Takeout export.

fn import(maxMetadataEntries?: number, chunkSize: number)

Scan extracted Google Takeout files and extract Google Photos GPS sidecars

Argument	Type	Required	Description
maxMetadataEntries?	number	no	Development-only limit: stop after N supplemental metadata files; output and coverage metrics are truncated.
chunkSize	number	yes	Evidence records per NDJSON output file; changes file layout, not the evidence set.

Resources

summary(infinite)— Summary of a Takeout metadata scan

Files

evidence(application/x-ndjson)— Generic location evidence in newline-delimited JSON

exclusions(application/x-ndjson)— Takeout exclusions; empty because this adapter emits none

@dieter/location-timelinev2026.09.18.1location_timeline.ts

Global Arguments

Argument	Type	Required	Description
sourceModelType	string	yes	Model type that produced enriched generic evidence.
sourceModelId	string	yes	Model ID that produced enriched generic evidence.
evidenceChunkNames	array	yes	Enriched generic evidence chunks to segment.

fn build(radiusKm: number, reviewGapHours: number, outputChunkSize: number)

Infer chronological episodes from generic location evidence

Argument	Type	Required	Description
radiusKm	number	yes	Maximum coordinate distance between grouped presence instants, in kilometres.
reviewGapHours	number	yes	Gap above which grouped instants require review, in hours.
outputChunkSize	number	yes	Episodes per NDJSON output file; changes file layout only.

Resources

summary(infinite)— Generic location-episode segmentation summary

Files

episodes(application/x-ndjson)— Source-neutral location episodes as NDJSON

03Reports2

@dieter/country-timelinemethod

country_timeline.ts

Country-level chronology with open bounds, travel context, and conflicts

@dieter/location-timelinemethod

location_timeline.ts

Detailed chronological location episodes, provenance, gaps, and conflicts

04Stats

100 / 100

Downloads

Archive size

80.9 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/Dieterbe/swamp-location-history

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64