location-conflation

🧩 Define complex geographic regions (geofences) by including and excluding country codes and GeoJSON shapes.

⚡️ Try it live at https://location-conflation.com/

---

What is it?

location-conflation generates GeoJSON features by combining other locations and shapes. It's a declarative way to describe geofences, so your application doesn't need to bundle or fetch large amounts of geodata.

A locationSet is an object with include and exclude arrays:

const locationSet = {
  include: [ /* locations */ ],
  exclude: [ /* locations */ ]
};

A location can be any of:

Kind	Example
A country-coder identifier (ISO codes, UN M.49 codes, Wikidata QIDs, etc.)	"de", "001", "conus", "gb-sct", "Q620634"
A custom .geojson filename (add custom features via the constructor or addFeatures)	"de-hamburg.geojson", "new_jersey.geojson"
A circular area [lon, lat, radius?] (radius in km, defaults to 25)	[8.67039, 49.41882], [-88.3726, 39.4818, 32]

---

Installing

Node

npm install @rapideditor/location-conflation

The package is distributed as both CJS and ESM:

const { LocationConflation } = require('@rapideditor/location-conflation');   // CJS
// or
import { LocationConflation } from '@rapideditor/location-conflation';        // ESM

Browser

Fetch the IIFE bundle from the jsDelivr CDN. Loading it via <script> exposes a LocationConflation global:

<script src="https://cdn.jsdelivr.net/npm/@rapideditor/location-conflation@latest/dist/js/location-conflation.iife.min.js"></script>
<script>
  const loco = new LocationConflation();
</script>

---

Examples

import { LocationConflation } from '@rapideditor/location-conflation';
import myFeatures from './fixtures/features.json' with { type: 'json' };   // optional
const loco = new LocationConflation(myFeatures);

Southern Europe

const result = loco.resolveLocationSet({ include: ['039'] });   // 039 = Southern Europe

Southern Europe and Northern Africa

const result = loco.resolveLocationSet({ include: ['039', '015'] });   // 015 = Northern Africa

Southern Europe and Northern Africa, excluding Egypt and Sudan

const result = loco.resolveLocationSet({ include: ['039', '015'], exclude: ['eg', 'sd'] });

The Alps, excluding Liechtenstein and regions around Bern and Zürich

const result = loco.resolveLocationSet({
  include: ['alps.geojson'],
  exclude: ['li', [8.55, 47.36], [7.45, 46.95]]
});

---

Spatial index

If your application has many objects with locationSet values (e.g. presets, rules, rendering styles) and you need to test which of them apply at a given point, the spatial-index API makes that lookup fast.

Register your objects once:

const presets = [
  { id: 'amenity/cafe', locationSet: { include: ['de'] } },
  { id: 'amenity/atm',  locationSet: { include: ['001'] } },      // 001 = world
  { id: 'parking/bike', locationSet: { include: ['us-nj.geojson'] } },
];
loco.registerLocationSets(presets);
// Each preset now has a stable `locationSetID`, e.g. '+[Q183]'

Then query by point as often as you like:

const hits = loco.locationSetsAt([8.68, 49.41]);   // Heidelberg
// => Map { '+[Q183]' => 357386, '+[Q2]' => 511207893 }
if (hits.has('+[Q183]')) { /* Germany preset applies here */ }

See the API reference for full details on registerLocationSets, locationSetsAt, rebuildIndex, and getLocationSetArea.

---

API

Full reference: API.md

Method	Purpose
new LocationConflation(features?)	Construct an instance, optionally seeded with custom .geojson features.
addFeatures / removeFeatures / clearFeatures	Manage the custom feature cache.
validateLocation / validateLocationSet	Validate without resolving geometry.
resolveLocation / resolveLocationSet	Validate and resolve to GeoJSON (cached).
registerLocationSets	Register locationSet-bearing objects for fast point-in-polygon lookups.
locationSetsAt	Query which indexed locationSets cover a point.
rebuildIndex / getLocationSetArea	Spatial-index maintenance / inspection.
LocationConflation.stringify	Pretty-print GeoJSON with sensible defaults.

---

Contributing

See CONTRIBUTING.md.

Thanks!

location-conflation is really a thin wrapper around these other great projects:

• country-coder — world boundaries
• polyclip-ts — polygon union / difference
• which-polygon — spatial index for custom shapes

License

Available under the ISC License. See LICENSE.md.