Regional Features

The NSI project has a collection of .geojson features corresponding to the internal or administrative borders of several countries for use with the locationSet property. These features represent a country's subdivisions, which can be referred to as either "states", "provinces", "regions", "counties", "districts", etc. The features use the local area's ISO 3166-2 naming conventions for their file names and id values.

List of available ISO 3166-2 compatible features

Below is a simplified, non-exhaustive list of available ISO 3166-2 compatible features within the NSI, which all require the .geojson extension when referenced. The table also lists a couple of exceptions where the .geojson extension is not needed; these subdivisions are built-in to the country-coder project and thus can be referenced directly without the .geojson file extension. For a full list of available features, please browse the NSI's features folder.

Location	Features	ISO Standard	Examples	Exceptions
Australia	States within Australia	ISO 3166-2:AU	Queensland (au-qld.geojson) Victoria (au-vic.geojson)	Tazmania (au-tas)
Austria	States of Austria	ISO 3166-2:AT	Vienna (at-9.geojson) Carinthia (at-2.geojson)	None
Canada	Canadian Provinces	ISO 3166-2:CA	Alberta (ca-ab.geojson) Quebec (ca-qc.geojson)	None
France	Regions within France	ISO 3166-2:FR	Île-de-France (fr-idf.geojson) Provence-Alpes-Côte-d’Azur (fr-pac.geojson)	None
Germany	States within Germany	ISO 3166-2:DE	Berlin (de-be.geojson) Hessen (de-he.geojson)	None
Japan	Prefectures of Japan	ISO 3166-2:JP	Chiba (jp-12.geojson) Aichi (jp-23.geojson)	None
New Zealand	Regions within New Zealand	ISO 3166-2:NZ	Marlborough (nz-mbh.geojson) Wellington (nz-wgn.geojson)	None
United States	States within the United States	ISO 3166-2:US	New Jersey (us-nj.geojson) California (us-ca.geojson)	Alaska (us-ak) Hawaii (us-hi)

There is partial support for Counties in Great Britain (UK) which follow the ISO 3166-2:GB standard. One exception is gb-lon.geojson, which represents London as a whole, but gb-lon isn't part of the ISO 3166-2:GB standard, as each London Borough has its own ISO value.

Using the features

The file names of the regional features follow the ISO 3166-2 standard for that country; e.g., US-FL.geojson for the feature representing the US state of Florida. If you wish to assign a locationSet area confined to a single region, you may use the id of the .geojson feature for that region, such as us-fl.geojson for Florida (note the difference in case from the feature's file name). For example:

"locationSet": {"include": ["us-fl.geojson"]}

You can also use multiple regions if need be, such as Florida & Georgia, for example:

"locationSet": {"include": ["us-ga.geojson","us-fl.geojson"]}

Or exclude regions, such as everywhere in the USA except for Florida & Georgia for example:

"locationSet": {
  "include": ["us"],
  "exclude": ["us-ga.geojson","us-fl.geojson"]
}

As previously mentioned, the subdivisions built-in to the country-coder project can be referenced directly without the .geojson file extension:

"locationSet": {"include": ["us-ak"]}
"locationSet": {"include": ["us-hi"]}

How to Update State/Region GeoJSONs

Originally posted by @jdcarls2 in #5449 (comment)

Updating and refining boundaries between adjacent GeoJSONs is not too hard. It is recommended that users wishing to perform such edits use QGIS. While QGIS 3.20 is pictured below, the tools used have been in the application for many versions, and users who opt for the LTR will be as able to perform these edits as those on the latest release.

Load the Data

Open a new project in QGIS. Browse to the repository in the Browser pane and find the features you wish to edit.

From there, you can simply drag the features into the map canvas. When adjusting a boundary, you must load all features which participate in that boundary. This will typically be between two or maybe three areas. While not strictly necessary, you may load all the features.

Topological Editing / Snapping

This is what ensures your edits do not create overlaps or gaps, so it's very important. On the Snapping Toolbar, click the magnet icon to enable snapping. The toolbar may not be visible at first; go to View > Toolbars > Snapping Toolbar from the menu bar, or right-click the toolbar area and select the snapping toolbar from the context menu.

On the toolbar, you will see an icon with three ways joined by a shared node:

Click this icon to enable topological editing.

Enable Editing

In QGIS, there is an Editing Toolbar. (Look for the pencil icon.) With a layer selected in the Layers pane, click the pencil icon for Toggle Editing. You can also right-click the layer and find this command in the context menu.

NOTE: You will need to repeat this for each layer being editing. If I adjust the IL / IN boundary with editing only enabled on IL, I will only affect the IL GeoJSON.

Vertex Editor

Near the Toggle Editing icon, you'll find the Vertex Editor icon, a hammer and screwdriver under a way/node. Click this to activate the Vertex Editor tool. The cursor will change to a crosshair, and as you hover over edges and nodes, they will highlight.

Click on a vertex to "pick it up", click again to "put it down". The same is true for edges and selections of multiple nodes, though in this context that is probably less useful. On the midpoint of any edge, a "helper node" is visible as a grey +. Clicking this will add a new vertex at that point, which can be dragged into the desired position.

Saving Edits

When there are pending edits, the Save icon will be enabled on the toolbar. Simply click the icon to save your edits to the layer.

NOTE: As with Toggle Editing, this button only applies to the currently selected layer. It's possible to successfully edit two layers and inadvertently only save the edits to a single layer. Fortunately, the Edit Toolbar does have a quicker way to save multiple edits. To the left of Toggle Editing is the Current Edits icon, two red pencils. Click this icon to open a small dropdown menu, where you can find the Save for All Layers command.

After Saving

Once you've saved your edits, you may commit the changes. If possible, run npm build first, though someone else can do this after the fact as well.

QGIS Suggestions

Here are a few things that might make your life easier using QGIS.

Reference Layers

For several versions, QGIS has come with the OSM carto tiles as a pre-configured XYZ Tile service, which you can find in the Browser pane. Drag this into your map to help guide your edits. You can also bring in aerial imagery, vector layers, etc.. Vector layers have the benefit of being "snappable".

By default, your vector layers come in as opaque areas. To make your reference layers actually useful, put them higher up on the layer list. For a raster layer like the OSM tiles, you can set the Blending Mode to something like multiply in order to view the layers below.

Use Groups

You can add layers to groups in the Layers pane. This makes it easier to keep different regions, reference layers, etc., separate, and keeps the layer list from getting too long.

Save a QGIS Project

Load all the features from the NSI repo and save your QGIS project. This will help save you setup time if you need to adjust other boundaries in the future.