Gvz API

This module interacts with an external GVZ (Gemeindeverzeichnis) API to automatically import coordinates and region aliases.

Apps

Configuration of GVZ API app

class integreat_cms.gvz_api.apps.GvzApiConfig(app_name, app_module)[source]

Bases: AppConfig

GVZ API config inheriting the django AppConfig

api_available: bool = False[source]

Whether the API is available

name: Final[str] = 'integreat_cms.gvz_api'[source]

Full Python path to the application

ready() None[source]

Checking if API is available

Return type:

None

verbose_name: Final[Promise] = 'GVZ API'[source]

Human-readable name for the application

Utils

Helper classes for Gemeindeverzeichnis API

class integreat_cms.gvz_api.utils.GvzApiWrapper[source]

Bases: object

Class that wraps around the GVZ (Gemeindeverzeichnis) API

api_url: str = 'https://gvz.integreat-app.de'[source]

The URL to the external GVZ API

best_match(region_name: str | None, division_type: str | None) dict[str, Any] | None[source]

Tries to find the correct region id (single search hit)

Parameters:
  • region_name (str | None) – name of a region (city name, county name, etc)

  • division_type (str | None) – administrative division type of region (choices: administrative_division)

Returns:

JSON search results defined in the GVZ API

Return type:

dict[str, Any] | None

get_child_coordinates(child_urls: list) dict[source]

Recursively get coordinates for list of children

Parameters:

child_urls (list) – URLs to REST API children

Returns:

dictionary of coordinates

Return type:

dict

get_details(ags: str) dict | None[source]

Get details for a region id (i.e. Gemeindeschlüssel)

Parameters:

ags (str) – Gemeindeschlüssel

Returns:

dictionary containing longitude, latitude, type, id, name

Return type:

dict | None

search(region_name: str | None, division_category: int | None) list[dict[str, Any]][source]

Search for a region and return candidates

Parameters:
  • region_name (str | None) – name of a region (city name, county name, etc)

  • division_category (int | None) – GVZ category of division (state, district, county, municipality)

Returns:

JSON search results defined in the GVZ API

Return type:

list[dict[str, Any]]

static translate_division_category(division_type: str | None) int | None[source]

Map Integreat CMS division types to Gemeindeverzeichnis division categories.

Parameters:

division_type (str | None) – type of a region

Returns:

division category identifier

Return type:

int | None

class integreat_cms.gvz_api.utils.GvzRegion(region_ags: str | None = None, region_name: str | None = None, region_type: str | None = None)[source]

Bases: object

Represents a region in the GVZ, initial values will be retrieved from API on initialization.

Parameters:
  • region_ags (str | None) – official ID for a region, i.e. Gemeindeschlüssel, defaults to None

  • region_name (str | None) – name of a region (city name, county name, etc), defaults to None

  • division_type – administrative division type of region (choices: administrative_division), defaults to None

  • region_type (str | None)

__init__(region_ags: str | None = None, region_name: str | None = None, region_type: str | None = None) None[source]

Load initial values for region from GVZ API

Parameters:
  • region_ags (str | None)

  • region_name (str | None)

  • region_type (str | None)

Return type:

None

as_dict() dict[str, Any][source]

Dictionary representation of region

Returns:

name, longitude, latitude, list of children

Return type:

dict[str, Any]