aio_taginfo.api.v4.key.prevalent_values

 1"""`/api/4/key/prevalent_values` endpoint."""
 2
 3from aio_taginfo.api.v4 import ObjectType, Response
 4from aio_taginfo.api.v4._internal import NonEmptyString, api_get_json, api_params
 5
 6from aiohttp import ClientSession
 7from pydantic import Field
 8from pydantic.dataclasses import dataclass
 9
10
11__all__ = (
12    "call",
13    "PrevalentValue",
14)
15
16
17@dataclass(kw_only=True, frozen=True)
18class PrevalentValue:
19    """
20    One value of a given tag and the number of times it was used.
21
22    Attributes:
23        value: The tag value or ``None`` to count the sum of the counts for all values not listed
24        count: Number of objects with this tag value
25        fraction: Fraction of number of objects with this tag value compared to all objects
26    """
27
28    value: str | None = Field(min_length=1, repr=True)
29    count: int = Field(ge=0, repr=True)
30    fraction: float = Field(ge=0.0, le=1.0, allow_inf_nan=False, repr=True)
31
32
33@dataclass(kw_only=True, frozen=True)
34class _Params:
35    key: NonEmptyString = Field(repr=True)
36    min_fraction: float = Field(ge=0.01, le=1.0, allow_inf_nan=False, repr=True)
37    filter: ObjectType = Field(repr=True)
38
39
40async def call(
41    key: str,
42    min_fraction: float = 0.01,
43    filter: ObjectType = ObjectType.ALL,  # noqa: A002
44    session: ClientSession | None = None,
45) -> Response[list[PrevalentValue]]:
46    """
47    Get most prevalent values used with a given key.
48
49    https://taginfo.openstreetmap.org/taginfo/apidoc#api_4_key_prevalent_values
50
51    Args:
52        key: tag key
53        min_fraction: only return values which are used in at least this percent
54                      of all objects with this key (defaults to 0.01)
55        filter: can be used to filter only values on tags used on nodes/ways/relations
56        session: request client session
57
58    Raises:
59        TaginfoError
60    """
61    params = api_params(_Params, key=key, min_fraction=min_fraction, filter=filter)
62    return await api_get_json(
63        path="key/prevalent_values",
64        cls=Response[list[PrevalentValue]],
65        session=session,
66        params=params,
67    )
68
69
70__docformat__ = "google"