Skip to content
Snowysauce edited this page Oct 13, 2024 · 9 revisions

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.

Screenshot from 2021-10-13 12-08-29

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.

Screenshot from 2021-10-13 12-14-10

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:

image

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.

image

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.

image

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

image

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.

image

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.

image

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.