Open APIs

 View Only
  • 1.  Location Management - Geographic area

    TM Forum Member
    Posted Jun 09, 2023 10:20
    Edited by Tomasz Ruchała Jun 12, 2023 03:46

    Hi all,

    I have a question regarding Location Management.

    On what entity from the Open API Geographic area should be modeled?
    Should it be the Geographic Address or some other entity that currently exists or does not exist but are in some future plan?

    Business context:

    Business cases that I want to cover are:

        - Marking resources as available for a specific geographic area.
        - Marking offers as available for a specific geographic area.
        - Make price depending on geographic area.

    In all these cases geographic area it's some area that (currently in all recognized cases) can be determined by one of the address components, e.g. administrative unit, province, or postal code. One geographic area can group one or more values for some component (e.g. two administrative units, or two cities)

    Analyse based on available TM forum materials:

    Currently, Open API in the Location Management area recognizes 3 entities:
    Geographic Site - described as an entity that can answer the question "where?"
    Geographic Address (and Sub-address) - described as places defined in a structured textual way (street name, street number …)
    Geographic Location - described as places defined as geometry in the spatial reference regarding the surface of the Earth

    In the TM Forum Open API specification I found an example in the Product Catalog Management area.
    For the product offering entity we have their "place" field, which is described: as "where the products are sold or delivered". In this place, there is used Geographic Address called "San Francisco Bay Area". There is no example with this entity, but my understanding is that it's not a detailed address with street and building number, but some area.


    "place": [
          "id": "9979",
          "href": "",
          "name": "San Francisco Bay Area",
          "@referredType": "GeographicAddress",
          "@type": "PlaceRef",
          "@baseType": "",
          "@schemaLocation": ""

    From another side in the TM forum Data Model, there is an entity named Area, but it's not used currently anywhere in TMForum APIs.

    There is also some topic on this forum that address the first case from a business context:

    Implementation context:
    Currently, in such cases, we use our Geo Area entity that is not mapped to any Open API entity. We want to change the implementation or use some translation for the current one to make this entity available via Open API.

    Tomasz Ruchała
    Comarch S.A.

  • 2.  RE: Location Management - Geographic area

    Posted Aug 29, 2023 03:47
    Edited by Dan d'Albuquerque Aug 29, 2023 03:54

    Hi Tomasz

    Within the Information Frameworx (SID), there is an entity known as "GeographicArea" which covers the use cases you describe above, such as the distribution channel responsible for a specific geographic area (see below)..  I would recommend extending the specific Open API (such as the Product Catalog API, Service Catalog API, Incident API, etc) to include the GeographicArea subclass of GeographicLocation (within the PlaceRef or RelatedPlaceRefOrValue).

    Also the geographic area that a product catalog is published in as below...

    Dan d'Albuquerque