Package: adm-boundary-manager
Administrative Boundaries ManagerLoad, manage and visualize administrative boundaries for a country or more, in Wagtail Projects.OverviewThe Admin Boundary Manager is a Wagtail based application that enables to load boundary datasets from different sources,
at different administrative levels as provided by the source, for a country. The boundaries can then be served as vector
tiles and used in web maps, and across your GIS based application that needs reference to a country and its boundaries.A countryis at the core of the package. This means that you will load boundary data country by country. You can have
multiple countries. This is a design decision specifically for this package. If you need to load, say continental data
at once, this might not be the best solution for your case.FeaturesLoad administrative boundaries from different sources. Supported sources include:OCHA's Administrative Boundary Common Operational Datasets (COD-AB)Global Administrative Areas 4.1 (GADM 4.1)Load data from other sources. At the core, we define a boundary model schema that you can follow to load data from
other sources not currently implemented out of the boxPreview loaded boundary data to check that everything is correct as expectedServe boundary data as vector tiles for use in your web maps. Data is saved to a PostGIS Table.ST_AsMVTis used to
serve vector tilesInstallationPrerequisitesYou need a Wagtail Project, with a PostGIS database setup, to support a GeoDjango project.InstallationYou can install the package using pip:pipinstalladm-boundary-managerUsageMake sure the following are all added to yourINSTALLED_APPSin your Wagtail settingsINSTALLED_APPS=["adminboundarymanager","django_countries","wagtailcache","wagtail.contrib.modeladmin","wagtail.contrib.settings","django.contrib.gis",]Run app migrationspythonmanage.pymigrateadminboundarymanagerAdd the following to your project'surls.pyurlpatterns=[...path("",include("adminboundarymanager.urls")),...]Wagtail Cache SetupThe package uses thewagtail-cachepackage for caching vector tile
requests. Please have a look at thewagtail-cache documentationfor setup
instructions.Accessing the settings and data loader interfaceTheAdmin Boundary settingswill be added to theWagtail Settingspanel automatically. To access theBoundary Dataloader and preview interfaces, you can follow the following steps:In an existing or new Wagtail app, add the following to thewagtail_hooks.pyfile. Create one if it does not exist
yet.fromwagtail.contrib.modeladmin.optionsimportmodeladmin_registerfromadminboundarymanager.wagtail_hooksimportAdminBoundaryManagerAdminGroupmodeladmin_register(AdminBoundaryManagerAdminGroup)This will add aBoundary Managermenu to the Wagtail Admin side panel, as in the below screenshot:Click to expand and access the submenuBoundary SettingsTheBoundary Settingsallow to configure settings used by the package. This
usesWagtail's Site Settingscontrib module.The following are the available settings, as shown in the screenshot below:Access theBoundary Managermenu, as described in the previous sectionClick onAdmin Boundary SettingsBoundary Data Source- Select where you will be getting your boundary data from. See following sections for more
details on the database model and supported data sourcesCountries must share boundaries- Check this if you plan to add boundaries for more than one country, and want to
validate that all the added countriesshare a boundary at least with one other country.Countries- Here you can add multiple countries that you wish to load data for.Save buttonBoundary Model StructureTheAdminBoundarymodel is a simpleGeodjangomodel with the following fieldsname_0name_1name_2name_3name_4gid_0gid_1gid_2gid_3gid_4levelgeomAs you might have noticed, the model supports up to 4 administrative levels. Thelevelfield indicates the specific
level for a given model instance.The fields starting with prefixname_correspond to thenameof the admin boundary at a given level. For
examplename_0corresponds to the name of the boundary at admin level 0, which is usually the country level.The fields starting with prefixgid_correspond to theIDof the admin boundary at a given level. For
examplegid_0corresponds to the id of the boundary at admin level 0, which is usually the country code in
eitheralpha2(2-letter code)
oralpha3(3-letter code) format.Thegeomfield is aGeodjangofield that stores the boundary geometry as aMultipolygon. Every boundary instance
is saved as a Multipolygon, even if it was initially a Polygon. This is to ensure consistency across the Model.Using this schema, you can format any boundary data to follow this structure and easily load it.TheLayerMappingutility is used under the hood
to load the boundaries from a GIS formatted file, that can be a shapefile or Geopackage, depending on the source.Supported Data SourcesCurrently, the following data sources are supported out of the box:OCHA's Administrative Boundary Common Operational Datasets (COD-AB)Global Administrative Areas 4.1 (GADM 4.1)OCHA COD AB - Accessing, downloading and loading OCHA's COD-CAB dataAdministrative Boundary CODsare baseline geographical datasets that are used by humanitarian agencies during preparedness and response activities.They are preferably sourced from official government boundaries but when these are unavailable the IM network must
develop and agree to a process to develop an alternate dataset.Where available, werecommendusing this data source since most of the data is sourced from official Government
sources. The boundary source covers most of African Countries.Download and organize COD-AB dataBelow are steps to download and load the boundary data for a country of interest:First you will need to access the
OCHA'sHumanitarian Data ExchangePlatform.
Thislinkwill take you directly to the COD-AB data download page, similar to the below screenshot:Make sureCODSis checked on the filter panel, underFeaturedsectionStill on the filter panel, under theData Seriessection, make sureCOD - Subnational Administrative Boundariesis checkedYou can search for your country of interest hereThe results will be shown here. Click on the country result to go to the download page, that will look similar to the
screenshot below:Once in the dataset detail page, follow the steps below to download the country boundariesshapefilesSelect theData and Resourcestab if not selected by defaultLook for theshapefiledataset. The file name will usually end withSHP.zip. This is the correct file that you
should downloadOnce you identify the shapefile, click on theDOWNLOADbutton to download the shapefileOnce downloaded, extract the shapefile to an accessible location in your computer. Once extracted, you will notice a
large number of files. That is ok.The files are for all the administrative levels, usually from 0 to 3, and also all levels combined. We want the data at
different levels. We will need togroup and zip the files for the same levels, as in the sample screenshot below:Group similar admin level files and zip them. Look out for patterns, for example for admin level 0 files, they will
contain the charactersadm0or similar somewhere in the middle of the name.Make sure for each level you have at-least 3 files with the following extensions:.shp.shx.dbfThese are the necessary files for a valid shapefile. You should end up with zip files for at least 3 levels.You can name the admin level zip files with an easy name that you can identify later. For example for level one, you can
have<country_name>_level_0.zipLoading COD-AB DataBefore accessing the data loading interface, make sure you have
selectedOCHA Administrative Boundary Common Operational Datasets (COD-ABS)as theBoundary data sourceoption in
theAdmin Boundary SettingsAlso make sure you add the countries of interest under theCountriessection in theAdmin Boundary SettingsClick on the Boundary ManagerClick on Boundary Data. This will open the boundary preview interface, with aAdd Boundarybutton in the top right
cornerClick on theAdd Boundarybutton, to open an interface that looks like in the below screenshotThis is the link to the data source, as described in the previous sectionSelect the country you want to load the data for. Make sure you select the country corresponding to the country data
you want to upload. To add a new country, you can do so from theAdmin Boundary SettingsSelect theAdministrative levelfor the country boundary data you want to uploadSelect the zipped shapefile for the country boundary level data. Make sure you select the correct zipped file for the
correct country and level. The file must be azipped shapefileas described the previous section.If done correctly, you will be redirected to the preview page, and see the data loaded on the map.If an error was encountered during the upload process, an error message will show up with details of the error.Repeat the process for all the administrative levels datasets that you want to load.NOTE:If you load data for an already existing level and country, the existing boundary data for that level and
country will be deleted and the new one saved.GADM 4.1 - Accessing, downloading and loading GADM 4.1 DataTheGlobal Administrative Areas 4.1 (GADM)is a database of the location of the world's
administrative areas (boundaries). Administrative areas in this database include: countries, counties, districts etc.
and cover every country in the world. For each area it provides some attributes foremost being the name and in some
cases variant names.The most recent version is4.1and is the version currently supported by this package.Download GADM 4.1 dataAccess theGADM datapage. It should look similar to below screenshot:Click on theDatalink from the navigation bar. The data page, at the time of writing, looks like the above
screenshot.Click on thecountrylink that will take you to a download interface for specific countries. Remember we have to do
it country by country in our upload interface.TheCountrydownload interface will look like below:Select your country of interest. GADM data should available for all countries in the world.Look for theGeopackagedownload link. For GADM data, downloading a geopackage comes with all the data for all the
different levels. This allows to upload data for different levels of a country with one step.Once you download thecountry geopackageand saved it somewhere in your computer, you are ready to load it.Load GADM 4.1 dataBefore accessing the data loading interface, make sure you have selectedGlobal Administrative Areas 4.1 (GADM)as
theBoundary data sourceoption in theAdmin Boundary SettingsGo toBoundary Data>Add Boundary. The upload form should look like belowLink to download data for country, as explained in previous sectionSelect the country for the data you downloaded. To add a new country, you can do so from
theAdmin Boundary SettingsChoose the geopackage file for the country data you downloadedClick on uploadIf done correctly, you will be redirected to the preview page, and see the data loaded on the map.If an error was encountered during the upload process, an error message will show up with details of the error.Repeat the process for all the countries' data that you want to load.NOTE:If you load data for an already existing country, the existing boundary data for that country will be deleted
and the new one saved.Boundary data from other sourcesAs explained in theBoundary Model Structuresection, by following the defined model
structure, you can add data from other sources.You will need to separate your country boundary dataset into the different levels. For example, for level 0 of a
country, you will have onezipped shapefile, as so on for all the levels you want to upload.Your shapefile data should contain the following fields, for each level.Level 0name_0gid_0Level 1name_0gid_0name_1gid_1Level 2name_0gid_0name_1gid_1name_2gid_2Level 3name_0gid_0name_1gid_1name_2gid_2name_3gid_3NOTE: The field names are case-insensitive. They can be in lowercase or uppercase.Loading data from other sourcesBefore accessing the data loading interface, make sure you have selectedGeneric Data Sourceas
theBoundary data sourceoption in theAdmin Boundary SettingsGo toBoundary Data>Add Boundary. The upload form should look like belowSelect the country to upload data forSelect the admin levelChoose yourzipped shapefilefor the selected admin levelClick onUploadto loadIf done correctly, you will be redirected to the preview page, and see the data loaded on the map.If an error was encountered during the upload process, an error message will show up with details of the error.Repeat the process for all the administrative levels datasets that you want to load for a country.Important notesFor consistency, you should decide on one data source and use it for all your countriesRe-uploading data for a given country and or level, will delete any existing data for that country and or level, and
replace with the new uploaded oneDeleting a country from the settings will delete any previously loaded data for that countryCache InvalidationWagtail Cache is invalidated automatically at the following points:On UpdatingAdminBoundarySettingsOn uploading or overwriting boundary dataData APIAPI endpoints are provided for searching, retrieving and serving vector tiles for the boundary data.Search endpoint/api/admin-boundary/search?search=<name>The search endpoint allows searching Admin Boundaries byname_0,name_1,name_2andname_3. This will give you
results for all boundaries whose name match the search phrase.Retrieve endpoint/api/admin-boundary/<boundary_id>The retrieve endpoint allows to get an admin boundary by ID. This assumes you already know the ID for the boundary
instance you wish to retrieve.Usually you will use this endpoint in conjunction with the search API.A sample use case will be:Use theSearch Endpointto search for an admin level by name in an autocomplete search inputShow the matching results in the result dropdownOnce the user selects a result item, you can use the theRetrieve endpointto retrieve the detail of the boundary,
using the ID of the selected boundary item.Vector Tiles Endpoint/api/admin-boundary/tiles/<int:z>/<int:x>/<int:y>The vector tiles endpoint can be used to serve the vector tiles from the boundary data. Usually, you will use this with
a web mapping library that supports vector tiles, likeMapLibre GL JSBelow is a quick snippet on how you can add boundary vector tile layers to your MapLibre web map:<head><linkrel="stylesheet"href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css"></head><body><divid="map"></div><scriptsrc="https://unpkg.com/maplibre-gl/dist/maplibre-gl.js"></script><script>constmap=newmaplibregl.Map({container:'map',// container idstyle:'https://demotiles.maplibre.org/style.json',// style URLcenter:[0,0],// starting position [lng, lat]zoom:1// starting zoom});constboundaryTilesUrl="/api/admin-boundary/tiles/{z}/{x}/{y}"map.on("load",()=>{// add sourcemap.addSource("admin-boundary-source",{type:"vector",tiles:[boundaryTilesUrl],})// add fill layermap.addLayer({'id':'admin-boundary-fill','type':'fill','source':'admin-boundary-source',"source-layer":"default",'paint':{'fill-color':"#fff",'fill-opacity':0,}});// add line layermap.addLayer({'id':'admin-boundary-line','type':'line','source':'admin-boundary-source',"source-layer":"default",'paint':{"line-color":"#444444","line-width":0.7,}});})</script></body>Note: The vector tilesource-layeris named asdefaultAll the fields are available in the vector tile data. This means you can show, on a popup for example, the data for a
boundary on click.You can also use this to filter which data is shown on the map.For example if you only wanted to show data for admin level 0, (i.e Country Level), you can do it as in the example
below:constboundaryFilter=["==","level",0]// add fill layer, with custom filtermap.addLayer({'id':'admin-boundary-fill','type':'fill','source':'admin-boundary-source',"source-layer":"default",'paint':{'fill-color':"#fff",'fill-opacity':0,},"filter":boundaryFilter});