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)

Bases: AppConfig

GVZ API config inheriting the django AppConfig

__init__(app_name, app_module)

api_available: bool = False

Whether the API is available

classmethod create(entry)

Factory that creates an app config from an entry in INSTALLED_APPS.

default_auto_field

get_model(model_name, require_ready=True)

Return the model with the given case-insensitive model_name.

Raise LookupError if no model exists with this name.

get_models(include_auto_created=False, include_swapped=False)

Return an iterable of models.

By default, the following models aren’t included:

• auto-created models for many-to-many relations without an explicit intermediate table,

• models that have been swapped out.

Set the corresponding keyword argument to True to include such models. Keyword arguments aren’t documented; they’re a private API.

import_models()

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

Full Python path to the application

ready() → None

Checking if API is available

Return type:

None

verbose_name: Final[Promise] = 'GVZ API'

Human-readable name for the application

Utils

Helper classes for Gemeindeverzeichnis API

class integreat_cms.gvz_api.utils.GvzApiWrapper

Bases: object

Class that wraps around the GVZ (Gemeindeverzeichnis) API

__init__()

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

The URL to the external GVZ API

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

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

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

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]]

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

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)

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

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]

Dictionary representation of region

Returns:

name, longitude, latitude, list of children

Return type:

dict[str, Any]