API Reference

Full reference for the LocationConflation class.

For a quick start, see the README.

Contents

Constructor & feature management

• new LocationConflation(featureCollection?)
• addFeatures(featureCollection)
• removeFeatures(...ids)
• clearFeatures()
• _cache — deprecated

Validation & resolution

• validateLocation(location)
• validateLocationSet(locationSet)
• resolveLocation(location)
• resolveLocationSet(locationSet)

Spatial index

• registerLocationSets(objects)
• rebuildIndex()
• locationSetsAt([lon, lat])
• getLocationSetArea(locationSetID)

Static helpers

• LocationConflation.stringify(object, options?)

---

Constructor

new LocationConflation(featureCollection?)

Constructs a new LocationConflation instance.

Optionally pass a GeoJSON FeatureCollection of custom features that can be referenced later as locations. Each feature must have a filename-like id ending in .geojson (on either feature.id or feature.properties.id). IDs are normalized to lowercase.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "new_jersey.geojson",
      "properties": { … },
      "geometry": { … }
    }
  ]
}

---

Feature management

addFeatures

loco.addFeatures(featureCollection: GeoJSON.FeatureCollection): void

Adds custom .geojson features into the internal resolved cache. Each feature must include an id ending in .geojson.

removeFeatures

loco.removeFeatures(...ids: string[]): void

Removes custom .geojson features by id (case-insensitive). Non-.geojson ids are ignored.

clearFeatures

loco.clearFeatures(): void

Clears all resolved-cache entries (_resolved) and re-seeds the world location and locationSet.

_cache

Backward-compatibility getter exposing the internal resolved cache as a Map.

---

Validation & resolution

validateLocation

loco.validateLocation(location: Location): ValidatedLocation

Validates a single location. Throws if the location is invalid.

A location can be any of:

Kind	Example	Notes
country-coder identifier	"de", "001", "conus", "gb-sct", "Q620634"	See country-coder. Full list at https://ideditor.codes.
Custom .geojson filename	"new_jersey.geojson"	Must have been passed to the constructor or addFeatures.
Point with radius	[8.67, 49.42], [-88.37, 39.48, 32]	[lon, lat, radius?]. Radius in km; defaults to 25.

On success, returns:

{
  type: 'point' | 'geojson' | 'countrycoder',
  location: /* the queried location */,
  id: /* stable identifier */
}

validateLocationSet

loco.validateLocationSet(locationSet: LocationSet): ValidatedLocationSet

Validates a locationSet. Throws if the locationSet or any of its components are invalid.

{
  include: [ /* locations */ ],
  exclude: [ /* locations */ ]
}

On success, returns:

{
  type: 'locationset',
  locationSet: /* the queried locationSet */,
  id: /* stable identifier */
}

resolveLocation

loco.resolveLocation(location: Location): ResolvedLocation

Like validateLocation, but also returns the resolved GeoJSON feature. Results are cached.

On success, returns the same shape as validateLocation plus a feature field containing the resolved GeoJSON.

resolveLocationSet

loco.resolveLocationSet(locationSet: LocationSet): ResolvedLocationSet

Like validateLocationSet, but runs the polygon-clipping operations and returns the resulting GeoJSON feature. Results are cached.

---

Spatial index

registerLocationSets

loco.registerLocationSets<T extends HasLocationSet>(objects: T[]): (T & HasLocationSetID)[]

Builds an inverted spatial index from objects that contain a locationSet property. Each object is annotated with a stable locationSetID and returned.

This method accumulates — calling it multiple times adds to the same index. To reset, construct a new LocationConflation instance.

const presets = [
  { id: 'amenity/cafe', locationSet: { include: ['de'] } },
  { id: 'amenity/atm',  locationSet: { include: ['001'] } },
];
loco.registerLocationSets(presets);
// presets[0].locationSetID === '+[Q183]'
// presets[1].locationSetID === '+[Q2]'

rebuildIndex

loco.rebuildIndex(): void

Rebuilds the internal spatial index from currently indexed locationSets and cached features.

locationSetsAt

loco.locationSetsAt(point: Vec2): Map<LocationSetID, number>

Returns a Map of the indexed locationSets whose resolved area covers the point [lon, lat], mapped to their approximate area in km².

Returning a Map gives callers O(1) has(locationSetID) membership tests — the common "is this locationSet valid here?" check — without a linear array scan. Results are not sorted; sort [...result.entries()] by value if you need that.

loco.registerLocationSets(presets);
const hits = loco.locationSetsAt([-75.16, 39.95]);
if (hits.has('+[Q30]')) { /* US preset applies here */ }
// Iterate smallest-first:
const sorted = [...hits.entries()].sort((a, b) => a[1] - b[1]);

getLocationSetArea

loco.getLocationSetArea(locationSetID: LocationSetID): number | undefined

Returns the approximate area (in km²) of an indexed locationSet, or undefined if it has not been indexed.

---

Static helpers

stringify

LocationConflation.stringify(obj: unknown, options?: StringifyOptions): string

Convenience wrapper around json-stringify-pretty-compact. options are passed through.

LocationConflation.stringify(someGeoJson, { maxLength: 100 });