Usage

Get items

The PyGADM lib can be used to extract information from the GADM dataset as GeoPandas GeoDataFrame.

Countries

Using the get_items methods, you can access an administrative area using either its name or its GADM identification code.

For exemple to extract the France geometry you can use the following code:

import pygadm
from ipyleaflet import GeoJSON, Map, basemaps

gdf = pygadm.get_items(name="France")

# display it in a map
m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])
m.add(GeoJSON(data=gdf.__geo_interface__, style={"color": "red", "fillOpacity": .4}))

m

If you know the code of the area you try to use, you can use the GADM code instead of the name.

import pygadm
from ipyleaflet import GeoJSON, Map, basemaps

gdf = pygadm.get_items(admin="FRA")

# display it in a map
m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])
m.add(GeoJSON(data=gdf.__geo_interface__, style={"color": "red", "fillOpacity": .4}))

m

Smaller admin levels

One is not bind to only request a country, any level can be accesed using both names and/or GADM code.

import pygadm
from ipyleaflet import GeoJSON, Map, basemaps

gdf = pygadm.get_items(name="Corse-du-Sud")

# display it in a map
m = Map(basemap=basemaps.Esri.WorldImagery, zoom=8, center=[41.86, 8.97])
m.add(GeoJSON(data=gdf.__geo_interface__, style={"color": "red", "fillOpacity": .4}))

m

Warning

The names of countries are all unique but not the smaller administrative layers. If you request a small area using name, make sure it’s the one you are looking for before running your workflow. follow Duplication issue for more information.

Content of an admin layer

Using the content_level option, one can require smaller administrative layer than the one setup in the name. For example when you request France, by setting up the content_level option to 2, the geodataframe will include all the department geometries.

import pygadm
from ipyleaflet import GeoJSON, Map, basemaps

gdf = pygadm.get_items(admin="FRA", content_level=2)

# display it in a map
m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=5, center=[46.21, 2.21])
m.add(GeoJSON(data=gdf.__geo_interface__, style={"color": "red", "fillOpacity": .4}))

m

Find names

To get the available name and GADM code in a administrative layer you can use the get_names method with the same parameters. Use then these names in a get_items request to get the geometry.

For example to get the name and codes of all the departments in France you can run:

import pygadm

pygadm.get_names(admin="FRA", content_level=2)

	NAME_2	GID_2
0	Ain	FRA.1.1_1
1	Allier	FRA.1.2_1
2	Ardèche	FRA.1.3_1
3	Cantal	FRA.1.4_1
4	Drôme	FRA.1.5_1
...	...	...
91	Alpes-Maritimes	FRA.13.2_1
92	Bouches-du-Rhône	FRA.13.3_1
93	Hautes-Alpes	FRA.13.4_1
94	Var	FRA.13.5_1
95	Vaucluse	FRA.13.6_1

96 rows × 2 columns

Google Earth engine

Note

We don’t display the results of these cells because the GEE authentification is not working in RDT.

Transform gdf into ee.FeatureCollection

If you want to use this lib with GEE, install the “earthengine-api” package in your environment and then run the following code:

import pygadm
import geemap
import ee
from ipyleaflet import basemaps, ZoomControl

ee.Initialize()

gdf = pygadm.get_items(name="Corse-du-Sud")

# transform into an ee.FeatureCollection
fc = ee.FeatureCollection(gdf.__geo_interface__)

# in this example we use geemap to display the geometry on the map
# the map is customized to have the same look & feel as the rest of the documentation
m = geemap.Map(scroll_wheel_zoom=False, center=[41.86, 8.97], zoom=8, basemap=basemaps.Esri.WorldImagery)
m.clear_controls()
m.add(ZoomControl())
m.addLayer(fc, {"color": "red"}, "FRA")

m

Simplify geometry

The GADM dataset are describing the geometry of administrative areas in high-resolution. This may overload the authorized importation limits of earthengine which will lead to the following error:

EEException: Request payload size exceeds the limit: 10485760 bytes.

Use the simplify method from GeoPandas (more informations here) to downscale the resolution of the geometries. The following example is needed if you want to work with France:

import pygadm
import geemap
import ee
from ipyleaflet import basemaps, ZoomControl

ee.Initialize()

gdf = pygadm.get_items(name="France")

# reduce resolution
gdf.geometry = gdf.geometry.simplify(tolerance=.001)

# transform into an ee.FeatureCollection
fc = ee.FeatureCollection(gdf.__geo_interface__)

# in this example we use geemap to display the geometry on the map
# the map is customized to have the same look & feel as the rest of the documentation
m = geemap.Map(scroll_wheel_zoom=False, center=[46.21, 2.21], zoom=5, basemap=basemaps.Esri.WorldImagery)
m.clear_controls()
m.add(ZoomControl())
m.addLayer(fc, {"color": "red"}, "FRA")

m

Duplication issue

Warning

The names of countries are all unique but not the smaller administrative layers. If you request a small area using name, make sure it’s the one you are looking for before running your workflow. If it’s not the case, use the get_names method to get the administrative code assosciated to the requested names, they are all unique.

Let’s demonstrate this behavior with the “Central” province of Singapore. First we try to load it using its name. It should return an error:

import pygadm

gdf = pygadm.get_items(name="Central")

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[6], line 3
      1 import pygadm
----> 3 gdf = pygadm.get_items(name="Central")

File ~/checkouts/readthedocs.org/user_builds/pygadm/checkouts/v0.1.1/pygadm/__init__.py:43, in get_items(name, admin, content_level)
     41 df = get_names(name, admin)
     42 if len(df) > 1:
---> 43     raise ValueError(
     44         f'The requested name ("{name}") is not unique ({len(df)} results). To retreive it, please use the `admin` parameter instead. If you don\'t know the GADM code, use the following code, it will return the GADM codes as well:\n`get_names(name="{name}")`'
     45     )
     46 level = df.columns[0].replace("NAME_", "")
     47 iso_3 = df.iloc[0][f"GID_{level}"][:3]

ValueError: The requested name ("Central") is not unique (9 results). To retreive it, please use the `admin` parameter instead. If you don't know the GADM code, use the following code, it will return the GADM codes as well:
`get_names(name="Central")`

As I don’t know the GADM code I copy/paste the suggested code from the error message and filter it by country ISO alpha-3 code. the ISO code is always displayed in the second column of the get_names output. All GADM code start with the country ISO code so you can use the provided cell for any admin level.

import pygadm

df = pygadm.get_names(name="Central")
df = df[df.iloc[:,1].str.startswith("SGP")]
df

	NAME_1	GID_1
6	Central	SGP.1_1

I now know that the code is “SGP.1_1” for the Central province so I can run my initial code again with the unique admin parameter:

import pygadm
from ipyleaflet import GeoJSON, Map, basemaps

gdf = pygadm.get_items(admin="SGP.1_1")

# display it in a map
m = Map(basemap=basemaps.Esri.WorldImagery,  zoom=11, center=[1.29, 103.83])
m.add(GeoJSON(data=gdf.__geo_interface__, style={"color": "red", "fillOpacity": .4}))

m