12rambau / pygadm

Easy access to administrative boundary defined by GADM from Python scripts

PyGADM

Overview

Easy access to administrative boundary defined by GADM from a Python scripts.

This lib provides access to GADM datasets from a Python script without downloading the file from their server. We provide access to The current version (4.1.) which delimits 400,276 administrative areas.

The data are freely available for academic use and other non-commercial use. Redistribution, or commercial use is not allowed without prior permission. See the license of the GADM project for more details.

Note

the dataset are generated in the GADM (Global Administrative Areas) project from Berkeley University. Any request relative to the geometries should be redirected to them.

install it using either pip or conda:

pip install pygadm

and then request area of interest from their name or GADM Id:

import pygadm

gdf = pygadm.AdmItems(name="Singapore", content_level=1)

Credits

This package was created with Copier and the @12rambau/pypackage 0.1.11 project template.

pygadm's Issues

Update template to 0.1.11

The package is based on the 0.1.5 version of @12rambau/pypackage.

The latest version of the template is 0.1.11.

Please consider updating the template to the latest version to include all the latest developments.

Run the following code in your project directory to update the template:

copier update --trust --defaults --vcs-ref 0.1.11

Note
You may need to reinstall copier and jinja2-time if they are not available in your environment.

After solving the merging issues you can push back the changes to your main branch.

use default_install_hook_types

default_install_hook_types	(optional: default [pre-commit]) a list of --hook-types which will be used by default when running pre-commit install.new in 2.18.0

default_install_hook_types
(optional: default [pre-commit]) a list of --hook-types which will be used by default when running pre-commit install.

new in 2.18.0

manage multiple versions

It would be nice if the tool could check multiple versions of GADM.

something like:

import pygadm 

pygadm.__gadm_version__ = 3.6 

and then the names and information would be gathered from the version 3.6 of the gadm database

ref to pygaul for EE users

documentation use of GEE is broken

the CI doesn't manage to build the documentation anymore.

add conda badge to readme

some admin names are cut

gpkg dataset (4.1) have some names cut e.g. "South Georgia and the South Sandwich Islands" => "South Georgia and the South San".

What should we do ?

add a prettier badge

Update template to 0.1.11

The package is based on the 0.1.5 version of @12rambau/pypackage.

The latest version of the template is 0.1.11.

Please consider updating the template to the latest version to include all the latest developments.

Run the following code in your project directory to update the template:

copier update --trust --defaults --vcs-ref 0.1.11

Note
You may need to reinstall copier and jinja2-time if they are not available in your environment.

After solving the merging issues you can push back the changes to your main branch.

cache the parquet database to avoid opening it all the time

use the geojson version of the files to reduce downloading times

The file can become completly huge with big countries like china (79Mo) or Brazil if donwloading the geopackage.
The geopackage is including all the geometry for all level, the geojson on the other hand is very lighweight as it only include the requested levels.

add a devcontainer

link the lib to pypackage

move to ruff

replace flake8 and isort by the more modern ruff

use list of request

to request multiple countries/admin areas at once. The request_level should remain the same

add gee credentials for the documentation

force the level of the request to avoid duplicates

There are duplication in the dataset everywhere even for names that should not bug:

• "Italy" which sould return a country returns a province of banglades
• "Cabo Verde" which should be a country returns a province of brazil

the use should be able to set level he requests with a value to avoid these errors

catch names that exist in multiple country

The name "Central" exist as a level 1 data in multiple country (singapore, cote d'ivoire ... etc). The lib should catch this situation and warn the user that the one proposed may not be the one expected and maybe show the list of corresponding GID so that the user can pick the more interesting one.

make the parameters privates in the docs and avoid exposing them

display all level information in get_names

Can't get level 0 data for Tanzania

Tried this

gdf = pygadm.Items(admin='TZA', content_level=0)

But I get this Exception

Exception: We cannot retrieve the data from GADM server. Try to manually open the following link: https://geodata.ucdavis.edu/gadm/gadm4.1/json/gadm41_TZA_0.json. If it doesn't work, the error is coming from GADM servers. If it works please open an issue on our repository: https://github.com/12rambau/pygadm/issues.

The link works fine. I have tried other countries, such as AUS, which seem to work fine, just having the issue with Tanzania. Please can someone help?

make sure that when 2 conflicting names exist the one taken is always the biggest

following #68

When loading data like mexico you get the department in philipine instead of the country from LATAM.

The database should be reorder to start with the unique country, then unique level 1 etc instead of being grouped by country as it's curently done.
It will create bugs in the name management workaround as the geojson and the table will not be aligned anymore.

Server down?

Hi,

I am trying to execute the code, that worked a few days back but fails today.

import pygadm

country_name = 'Kenya'
adm_level = 1
gdf = pygadm.get_items(name=country_name, content_level=adm_level)

Output are different:

DriverError: CURL error: Failed to connect to geodata.ucdavis.edu port 443 after 21037 ms: Couldn't connect to server

And another one:

DriverError: CURL error: SSL/TLS connection timeout

How do I download disputed territories?

I was trying to download data for disputed territories e.g.

pygadm.Items(admin="Z01", content_level=2) # Jammu & Kashmir (India)

However, this doesn't work.

Z01 is actually included within the file for India on gadm.org, but pygadm.Items(admin="IND", content_level=2) doesn't download it either -- it only includes the features whose GID_0 is IND. Any help?

remove the jupyter_execute folder

For no reason jupyter-sphinx generates a jupyter-execute folder. It should not be added to the distant version of the repository.

related to :

• jupyter/jupyter-sphinx#215

Names of the administrative fields are all set in CamelCase

Specify the level you are looking for

For some names there exist duplicated areas that are perfect match e.g. "mexico" that can be both a country and a region in phillipines.
I wanted to set some ordering in the search tool to make sure countries were handled first. But this will reorder the names with respect to the one from the Json file and break the Item function workaround for camelCase names.

So instead I think the user should specify what level he is specifically looking for.

THis involve reducing the scope of the search and slightly modify the error message when multiple countries are found.

ADM0 boundaries for china and india

Describe the bug
Using the pygadm import, I tried to call all of the admin 0 boundaries for countries. admin codes IND and CHN returned this error: "Error occurred: Must have equal len keys and value when setting with an iterable"

To Reproduce
Steps to reproduce the behavior:

1. open a new python script
2. type in pygadm.Items(admin="IND", content_level=-1 )

manage continent requests

special case requests for continents so that people can get all countries in 1 request

doc build is broken

use Items and Names it's better ;-)

yes I know it's the third time I change but I think it's the lats because it cannot be simplified more and it looks robust enough to be understood by anyone.

remove secondary sidebar on the landing page

Unable to load Items by name

Describe the bug

Names returns the right admin code but no geometries are returned using Items

To Reproduce

Pass United States, South Africa by name to Items no geometries are returned.
Will return geometries only by admin so USA and ZAF

Screenshots

improve management of duplications

SOme duplicate are not at the same level and thus are missed by the get_names method. This should be changed so that user don't get lost when they type "Italy" or "Uganda"

use classes for items and names

the functional paradigm is working just fine but to make it clearer to users that the result of each function is an object I could make them objcts as well:

Name ?
Admin ?

get_names without arguments to get the list of all countries

It will virtually return the complete dataset but who cares ?

Can't read Names from a list of names

Describe the bug

Can't read names from a list of names

To Reproduce
Steps to reproduce the behavior:

Pass a list of strings such as Names(name=["France", "Germany", "Italy'])

Screenshots