overturetoosm.places

Convert Overture's places features to OSM tags.

  1"""Convert Overture's `places` features to OSM tags."""
  2
  3from typing import Literal, Dict
  4
  5from .objects import PlaceProps, UnmatchedError, ConfidenceError
  6from .resources import places_tags
  7
  8
  9def process_place(
 10    props: dict,
 11    confidence: float = 0.0,
 12    region_tag: str = "addr:state",
 13    unmatched: Literal["error", "force", "ignore"] = "ignore",
 14) -> Dict[str, str]:
 15    """Convert Overture's places properties to OSM tags.
 16
 17    Example usage:
 18    ```python
 19    import json
 20    from overturetoosm import process_place
 21
 22    with open("overture.geojson", "r", encoding="utf-8") as f:
 23        contents: dict = json.load(f)
 24
 25        for feature in contents["features"]:
 26            feature["properties"] = process_place(feature["properties"], confidence=0.5)
 27
 28    with open("overture_out.geojson", "w+", encoding="utf-8") as x:
 29        json.dump(contents, x, indent=4)
 30    ```
 31    Args:
 32        props (dict): The feature properties from the Overture GeoJSON.
 33        region_tag (str, optional): What tag to convert Overture's `region` tag to.
 34            Defaults to `addr:state`.
 35        confidence (float, optional): The minimum confidence level. Defaults to 0.0.
 36        unmatched (Literal["error", "force", "ignore"], optional): How to handle
 37            unmatched Overture categories. The "error" option raises an UnmatchedError
 38            exception, "force" puts the category into the `type` key, and "ignore"
 39            only returns other properties. Defaults to "ignore".
 40
 41    Returns:
 42        dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema.
 43
 44    Raises:
 45        `overturetoosm.objects.UnmatchedError`: Raised if `unmatched` is set to `error` and
 46            the Overture category has no OSM definition.
 47        `overturetoosm.objects.ConfidenceError`: Raised if the confidence level is set
 48            above a feature's confidence.
 49    """
 50    new_props = {}
 51    prop_obj = PlaceProps(**props)
 52    if prop_obj.confidence < confidence:
 53        raise ConfidenceError(confidence, prop_obj.confidence)
 54
 55    if prop_obj.categories:
 56        prim = places_tags.get(prop_obj.categories.main)
 57        if prim:
 58            new_props = {**new_props, **prim}
 59        elif unmatched == "force":
 60            new_props["type"] = prop_obj.categories.main
 61        elif unmatched == "error":
 62            raise UnmatchedError(prop_obj.categories.main)
 63
 64    if prop_obj.names.primary:
 65        new_props["name"] = prop_obj.names.primary
 66
 67    if prop_obj.phones is not None:
 68        new_props["phone"] = prop_obj.phones[0]
 69
 70    if prop_obj.websites is not None:
 71        new_props["website"] = prop_obj.websites[0]
 72
 73    if add := prop_obj.addresses[0]:
 74        if add.freeform:
 75            new_props["addr:street_address"] = add.freeform
 76        if add.country:
 77            new_props["addr:country"] = add.country
 78        if add.postcode:
 79            new_props["addr:postcode"] = add.postcode
 80        if add.locality:
 81            new_props["addr:city"] = add.locality
 82        if add.region:
 83            new_props[region_tag] = add.region
 84
 85    if prop_obj.sources:
 86        new_props["source"] = (
 87            ", ".join({i.dataset for i in prop_obj.sources}) + " via overturetoosm"
 88        )
 89
 90    if prop_obj.socials is not None:
 91        for social in prop_obj.socials:
 92            if "facebook" in social:
 93                new_props["contact:facebook"] = social
 94            elif "twitter" in social:
 95                new_props["contact:twitter"] = social
 96
 97    if prop_obj.brand:
 98        new_props["brand"] = prop_obj.brand.names.primary
 99        new_props["brand:wikidata"] = prop_obj.brand.wikidata
100
101    return new_props
def process_place( props: dict, confidence: float = 0.0, region_tag: str = 'addr:state', unmatched: Literal['error', 'force', 'ignore'] = 'ignore') -> Dict[str, str]:
 10def process_place(
 11    props: dict,
 12    confidence: float = 0.0,
 13    region_tag: str = "addr:state",
 14    unmatched: Literal["error", "force", "ignore"] = "ignore",
 15) -> Dict[str, str]:
 16    """Convert Overture's places properties to OSM tags.
 17
 18    Example usage:
 19    ```python
 20    import json
 21    from overturetoosm import process_place
 22
 23    with open("overture.geojson", "r", encoding="utf-8") as f:
 24        contents: dict = json.load(f)
 25
 26        for feature in contents["features"]:
 27            feature["properties"] = process_place(feature["properties"], confidence=0.5)
 28
 29    with open("overture_out.geojson", "w+", encoding="utf-8") as x:
 30        json.dump(contents, x, indent=4)
 31    ```
 32    Args:
 33        props (dict): The feature properties from the Overture GeoJSON.
 34        region_tag (str, optional): What tag to convert Overture's `region` tag to.
 35            Defaults to `addr:state`.
 36        confidence (float, optional): The minimum confidence level. Defaults to 0.0.
 37        unmatched (Literal["error", "force", "ignore"], optional): How to handle
 38            unmatched Overture categories. The "error" option raises an UnmatchedError
 39            exception, "force" puts the category into the `type` key, and "ignore"
 40            only returns other properties. Defaults to "ignore".
 41
 42    Returns:
 43        dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema.
 44
 45    Raises:
 46        `overturetoosm.objects.UnmatchedError`: Raised if `unmatched` is set to `error` and
 47            the Overture category has no OSM definition.
 48        `overturetoosm.objects.ConfidenceError`: Raised if the confidence level is set
 49            above a feature's confidence.
 50    """
 51    new_props = {}
 52    prop_obj = PlaceProps(**props)
 53    if prop_obj.confidence < confidence:
 54        raise ConfidenceError(confidence, prop_obj.confidence)
 55
 56    if prop_obj.categories:
 57        prim = places_tags.get(prop_obj.categories.main)
 58        if prim:
 59            new_props = {**new_props, **prim}
 60        elif unmatched == "force":
 61            new_props["type"] = prop_obj.categories.main
 62        elif unmatched == "error":
 63            raise UnmatchedError(prop_obj.categories.main)
 64
 65    if prop_obj.names.primary:
 66        new_props["name"] = prop_obj.names.primary
 67
 68    if prop_obj.phones is not None:
 69        new_props["phone"] = prop_obj.phones[0]
 70
 71    if prop_obj.websites is not None:
 72        new_props["website"] = prop_obj.websites[0]
 73
 74    if add := prop_obj.addresses[0]:
 75        if add.freeform:
 76            new_props["addr:street_address"] = add.freeform
 77        if add.country:
 78            new_props["addr:country"] = add.country
 79        if add.postcode:
 80            new_props["addr:postcode"] = add.postcode
 81        if add.locality:
 82            new_props["addr:city"] = add.locality
 83        if add.region:
 84            new_props[region_tag] = add.region
 85
 86    if prop_obj.sources:
 87        new_props["source"] = (
 88            ", ".join({i.dataset for i in prop_obj.sources}) + " via overturetoosm"
 89        )
 90
 91    if prop_obj.socials is not None:
 92        for social in prop_obj.socials:
 93            if "facebook" in social:
 94                new_props["contact:facebook"] = social
 95            elif "twitter" in social:
 96                new_props["contact:twitter"] = social
 97
 98    if prop_obj.brand:
 99        new_props["brand"] = prop_obj.brand.names.primary
100        new_props["brand:wikidata"] = prop_obj.brand.wikidata
101
102    return new_props

Convert Overture's places properties to OSM tags.

Example usage:

import json
from overturetoosm import process_place

with open("overture.geojson", "r", encoding="utf-8") as f:
    contents: dict = json.load(f)

    for feature in contents["features"]:
        feature["properties"] = process_place(feature["properties"], confidence=0.5)

with open("overture_out.geojson", "w+", encoding="utf-8") as x:
    json.dump(contents, x, indent=4)
Arguments:
  • props (dict): The feature properties from the Overture GeoJSON.
  • region_tag (str, optional): What tag to convert Overture's region tag to. Defaults to addr:state.
  • confidence (float, optional): The minimum confidence level. Defaults to 0.0.
  • unmatched (Literal["error", "force", "ignore"], optional): How to handle unmatched Overture categories. The "error" option raises an UnmatchedError exception, "force" puts the category into the type key, and "ignore" only returns other properties. Defaults to "ignore".
Returns:

dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema.

Raises: