Usage#

Get admininstrative items#

The PyGAUL lib can be used to extract information from the FAO GAUL dataset as ee.FeatureCollection.

Note

ee.FeatureCollection can easily be converted to GeoDataFrame but if interacting with Earthengine is not the chore of your usage, have a look to pygadm. It will provide accès to smaller administrative boundaries and return directly a gdf.

Important

PyGAUL is not managing the connection to Google Earth Engine API. The user is responsible to set up the Initialization as he see fit. This is a feature to allow users with exotic GEE connection (e.g. service accounts) to continue use the lib without any modification.

Countries#

Using the Items class, you can access an administrative area using either its name or its GAUL identification code.

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

import pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(name="France")

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

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

import pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(admin="301")

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

Smaller admin levels#

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

import pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(name="Corse-du-Sud")

# display it in a map
m = Map(zoom=8, center=[41.86, 8.97])
m.addLayer(fc, {"color": "red"}, "")
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.

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 pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(admin="301", content_level=2)

# display it in a map
m = Map(zoom=5, center=[46.21, 2.21])
m.addLayer(fc, {"color": "red"}, "")
m

Request multiple areas at once#

To perform regional analysis that aggregate multiple boundaries, you can now request them at once using a list of name or a list of admin. In this example we request both germany and France at once:

import pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(name=["France", "Germany"], content_level=1)

# display it in a map
m = Map(zoom=5, center=[48.83, 5.17])
m.addLayer(fc, {"color": "red"}, "")
m

Continents#

It’s possible to request all countries from one single continent using one of the following names:

North America
South America
Antartica
Europe
Asia
Oceania
Africa

import pygaul
from pygaul import utils
from geemap import Map

utils.initialize_documentation()

fc = pygaul.Items(name="Europe")

# display it in a map
m = Map(zoom=4, center = [49.38237278700955, 31.464843750000004])
m.addLayer(fc, {"color": "red"}, "")
m

Find administrative names#

To get the available name and GAUL code in a administrative layer you can use the Names class with the same parameters. Use then these names in a Items request to get the geometry.

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

import pygaul

pygaul.Names(admin="301", content_level=2) # france

	gaul2_name	gaul2_code
0	Ardèche	135317
1	Cantal	135318
2	Drôme	135319
3	Haute-Loire	135320
4	Isère	135322
...	...	...
91	Loire-Atlantique	135392
92	Maine-Et-Loire	135393
93	Mayenne	135394
94	Sarthe	135395
95	Vendée	135396

96 rows × 2 columns

Note

If needed, one can get the names of the upper administrative layers by setting the complete parameter to True.

import pygaul

pygaul.Names(name="Auvergne-Rhône-Alpes", content_level=2, complete=True)

	continent	gaul0_code	gaul0_name	gaul1_code	gaul1_name	gaul2_code	gaul2_name	iso3_code
0	europe	301	France	3431	Auvergne-Rhône-Alpes	135317	Ardèche	FRA
1	europe	301	France	3431	Auvergne-Rhône-Alpes	135318	Cantal	FRA
2	europe	301	France	3431	Auvergne-Rhône-Alpes	135319	Drôme	FRA
3	europe	301	France	3431	Auvergne-Rhône-Alpes	135320	Haute-Loire	FRA
4	europe	301	France	3431	Auvergne-Rhône-Alpes	135322	Isère	FRA
5	europe	301	France	3431	Auvergne-Rhône-Alpes	135315	Ain	FRA
6	europe	301	France	3431	Auvergne-Rhône-Alpes	135316	Allier	FRA
7	europe	301	France	3431	Auvergne-Rhône-Alpes	135321	Haute-Savoie	FRA
8	europe	301	France	3431	Auvergne-Rhône-Alpes	135323	Loire	FRA
9	europe	301	France	3431	Auvergne-Rhône-Alpes	135324	Puy-De-Dôme	FRA
10	europe	301	France	3431	Auvergne-Rhône-Alpes	135325	Rhône	FRA
11	europe	301	France	3431	Auvergne-Rhône-Alpes	135326	Savoie	FRA

Note

You can also get the list of all the country names by omitting admin and name parameters. If a level is not provided the table will only show country names but other parameters remain availables.

pygaul.Names()

Suggestion#

If you make an error when writing the name of your input, the error message will suggest 5 potential candidates in the existing names of the GADM dataset:

import pygaul
from pygaul import utils

utils.initialize_documentation()

fc = pygaul.Items(name="Franc")

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[9], line 6
      2 from pygaul import utils
      4 utils.initialize_documentation()
----> 6 fc = pygaul.Items(name="Franc")

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/stable/lib/python3.10/site-packages/ee/computedobject.py:29, in ComputedObjectMetaclass.__call__(cls, *args, **kwargs)
     27   return args[0]
     28 else:
---> 29   return type.__call__(cls, *args, **kwargs)

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/stable/lib/python3.10/site-packages/pygaul/__init__.py:166, in Items.__init__(self, name, admin, content_level)
    162     names = [""]
    164 # use itertools, normally one of them is empty so it will raise an error
    165 # if not the case as admin and name will be set together
--> 166 fc_list = [self._items(n, a, content_level) for n, a in product(names, admins)]
    168 # concat all the data
    169 feature_collection = fc_list[0]

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/stable/lib/python3.10/site-packages/pygaul/__init__.py:166, in <listcomp>(.0)
    162     names = [""]
    164 # use itertools, normally one of them is empty so it will raise an error
    165 # if not the case as admin and name will be set together
--> 166 fc_list = [self._items(n, a, content_level) for n, a in product(names, admins)]
    168 # concat all the data
    169 feature_collection = fc_list[0]

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/stable/lib/python3.10/site-packages/pygaul/__init__.py:191, in Items._items(self, name, admin, content_level)
    179 """
    180 Return the requested administrative boundaries from a single name or administrative code.
    181 
   (...)
    188     The FeatureCollection of the requested area with all the GAUL attributes.
    189 """
    190 # call to Names without level to raise an error if the requested level won't work
--> 191 df = Names(name, admin)
    192 if len(df) > 1:
    193     raise ValueError(
    194         f'The requested name ("{name}") is not unique ({len(df)} results). '
    195         f"To retrieve it, please use the `admin` parameter instead. "
    196         f"If you don't know the GAUL code, use the following code, "
    197         f'it will return the GAUL codes as well:\n`Names(name="{name}")`'
    198     )

File ~/checkouts/readthedocs.org/user_builds/pygaul/envs/stable/lib/python3.10/site-packages/pygaul/__init__.py:81, in Names.__init__(self, name, admin, content_level, complete)
     79     else:
     80         close_ids = [i.upper() for i in close_ids]
---> 81     raise ValueError(
     82         f'The requested "{id}" is not part of FAO GAUL 2024. The closest '
     83         f'matches are: {", ".join(close_ids)}.'
     84     )
     86 # Get the code of the associated country of the identifed area and the associated level
     87 line = is_in[~((~is_in).all(axis=1))].idxmax(1)

ValueError: The requested "Franc" is not part of FAO GAUL 2024. The closest matches are: France, Franca, Ranco, Franciou, Rancul.

Usage#

Get admininstrative items#

Countries#

Smaller admin levels#

Content of an admin layer#

Request multiple areas at once#

Continents#

Find administrative names#

Suggestion#

This Page