Open APIs

Expand all | Collapse all

TMF673 - GeographicAddress - Building

  • 1.  TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 19, 2021 14:58
    Hi

    I am trying to model the address below using TMF673 Geographic Address but it does not seem to fit.

    Riverside Tower, 5, Lanyon Place, Belfast, BT1 3BT

    The part at issue is the building name, 'Riverside Tower'. There appears to be no suitable field in the GeographicAddress resource to hold it. The following have been suggested :-

    name - this seems unsuitable as it appears to be some sort of friendly name rather than the official name of the building which constitutes the address
    GeographicSubAddress.buildingName - this also seems unsuitable as there is no sense in which 'Riverside Tower' is a property of a sub-address. Rather, it acts as the defining characteristic of the address, equal to (and possibly an alternative to) the street number (5)

    I was probably expecting to find something in the GeographicAddress resource like 'building' or 'premisesName' in which to place it.

    Any help appreciated, Darren

    ------------------------------
    Darren Wylie
    BT Group plc
    ------------------------------


  • 2.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 01:32

    Hi Dareen,

    If I understand correctly 'Riverside Tower' is building name, remaining part is flat , block and etc.
     I believe you can use the below options.

    GeographicSubAddress.buildingName for your building name
    GeographicSubAddress.subUnitType -  for TOWER, FLAT
    GeographicSubAddress.subUnitNumber - for FLAT no
    GeographicSubAddress.levelType - eg : floor, basement
    GeographicSubAddress.levelTypeNumber - eg : 2nd floor, basement 2

    specification pdf

    Hope this helps



    ------------------------------
    Srikanthbabu Komma
    Capgemini
    ------------------------------



  • 3.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 03:48
    Hi - thanks for the reply but this implies that 'Riverside Tower' is in some way descriptive of a sub-address of the property.
    This is exactly the point of contention - I don't/can't regard 'Riverside Tower' as anything but a property of the address, not some sort of sub-address.

    I can regard, however, Floor 2 as a sub-address within 'Riverside Tower' but Riverside Tower itself is not within 'Riverside Tower' - it cannot be within itself.

    Someone else has replied who indicated that geographicAddress is a bit basis to be useful and that it is likely that 'building' will be introduced into it.

    Thanks

    ------------------------------
    Darren Wylie
    BT Group plc
    ------------------------------



  • 4.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 03:58
    We might be talking at cross purposes but as far as the definition I'm working on building name is a property of the address and there are also sub building details defined in the address which Openreach provides currently over the existing non-TMF APIs. Again as an example, the second floor is listed as a sub-building as you describe along with other areas in the building.

    ------------------------------
    Steve Ranford-Bragg
    BT Group plc
    ------------------------------



  • 5.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 04:47
    Edited by Florin Tene Oct 20, 2021 04:51
    Hi, there are several changes coming in the new version of the TMF673 in regards to management operations support but also in regards to the data model (e.g., countryCode & ISO code,  addressType, externalIdentifiers, multiple sub-addresses, etc.).
    At the moment I couldn't find any ticket to cover this request, as such, I've created a new one to be discussed for the future versions of the API.

    Thank you,
    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 6.  RE: TMF673 - GeographicAddress - Building

    Posted Oct 20, 2021 07:16
    Hello All

    Address formats can cause all sorts of fun.

    There is a whole technical committee in ISO working on this as part of " ISO 19160-4:2017".

    Any folks proposing to make extensions to this API might want to think carefully from the point of view of interoperability.

    From a UK PostOffice Address File perspective.

    I do not know what is proposed in the new version of TMF673 but it seems reasonable to me to add Building Name to Geographic Address (it is not a SubAddress).

    You might also consider what to do with premises which have a building number range (eg. 18a-20). Programming guidance from the Royal Mail is to use the Building Name for that.

    Also in the UK one can have a second line for Thoroughfare/Street Name and Descriptor  and Locality (known as the Dependent Thoroughfare Name and Dependent Locality). These are used to identify when the same Thoroughfare name is used more than once in an post town or when one wants to identify a locality like a business park within a locality.

    And then someone might want to consider Organisation name to be added also when dealing with visiting premises with multiple business tenants.



    ------------------------------
    Derrick Evans
    ------------------------------



  • 7.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 07:26
    Hi Derrick,

    Hope you're well :-)

    Those are the kinds of things I'm adding into the sub-classed address object for Openreach based on the model we use currently on the existing service, as you will remember fondly I'm sure! The problem I can see is that address varies by locality so a generic model could be difficult to create but possibly this is something that's being addressed in the new standard?

    ------------------------------
    Steve Ranford-Bragg
    BT Group plc
    ------------------------------



  • 8.  RE: TMF673 - GeographicAddress - Building

    Posted Oct 20, 2021 07:43
    Hello Steve

    I am fine thanks.
    Glad to see you are moving things forward on the API front.

    You are correct there are many different formats of addresses around the world. Maybe we should all use what three words!

    In UBL they used StreeName and then AdditionalStreetName (and that could then cover dependent thoroughfare name.)

    Adding Organisation Name and having two fields for thoroughfare and locality would cover many of the bases.

    The only other option is to have address lines 1..n. Which to my mind does not help much.

    ------------------------------
    Derrick Evans
    ------------------------------



  • 9.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 07:40
    Edited by Florin Tene Oct 20, 2021 07:58
    Hi,

      Indeed the address format is a very special "fun".

      I believe we all have to be aware that the TMF673 was not designed only for UK, it needs to be generic enough to fullfill the requirements from all over the world.
      The input model for the GeographicAddress is from TMForum SID.

      Regarding the building number range, i believe it was always mapped against the StreetNr & StreetNrLast - i'm not sure but I do believe the building number range corresponds to the street number range. - not sure, i might be wrong.
      Business park, shopping center etc concepts are captured through the use of SubAddress.

      Although, I can see the the reason behind the buildingName scenario, i'm not so sure about Organisation related details inside the GeographicAddress. The Organisation is a type of Party and as such the relationship is captured in that way (Party - Address).  Organisations could be today at one address, tomorrow at a different addres, they have different life cycles as entities and the relationship is already captured as mentioned above.

       Anyway, I believe we can raise suggestions, or new improvements ideas for next releases of the TMF APIs.

    Thank you,
    Florin

    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 10.  RE: TMF673 - GeographicAddress - Building

    Posted Oct 20, 2021 08:05
    Thanks
    I missed the StreetNrLast, so yes you are correct on that.

    I also get the discussion about Organisation Name and the notion of Parties.

    But in Royal Mail PAF Organisation Name is part of an address for some premises.

    If I look up my address online the address does not have my name as the occupant.

    But there are plenty of addresses that have companies like Oracle or HSBC as part of the recorded address.

    In fact, it is possible for very large organisation in a building to have their own postcode for the same building that they occupy with others leading to a building having two or more postcodes.

    ------------------------------
    Derrick Evans
    ------------------------------



  • 11.  RE: TMF673 - GeographicAddress - Building

    Posted Oct 25, 2021 07:15
    Edited by Tomáš Hajný Oct 25, 2021 07:15
    Hi,

    Obviously, you're right that the Organisation (or Party in general) is a related entity to the Address. However, there's also the use case (especially for one time delivery, e.g. in case of a particular order) in which a physical person wants to get something delivered to his/her working place. In this case, the Organisation _is_ just part of the address, because there's no relation between the service provider and this Organisation as a party. Just for completeness...

    ------------------------------
    Tomáš Hajný
    ČD - Telematika
    ------------------------------



  • 12.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 29, 2021 11:28
    Hi Tomas,

    I guess we need to differentiate the Delivery address (that actually describes where courier has to go to) and Geografic address, the one that refers to certain place on the map.

    My view is that a delivery address, by its purpose,  may include a geographic address and whatever is useful to ensure smooth delivery (receipient name, some description of the location - "meet me at the gate 4 close to blue kiosk").

    Unlike delivery GeographicalAddress is just a point on the map and should rather describe what's located there. For me this is generic, but essential information on environment that is used for plenty of scenarios (e.g. Feasibility check for wireline).

    In regard to the conversation on whether Organization renting/owning a property is a Party or not: I do believe that this is a case when Organization should not be modelled as a Party. E.g. there could be Organization that has no relationship with this  particular CSP. Frankly it makes very little sense to create all known Orgs as Parties.
    On the other hand, I'm sure Organization name can't be considered as a part of the address itself except for the cases it's officially a part of the address (Derrick gave a nice example). Having said this, I still think that some sort of additional descriptors that precisely point out to the particular place and sometimes can be used instead of nicely formatted addresses would certainly be useful (e.g. Kremlin or Big Ben).

    ------------------------------
    Victor Anfimov
    Rostelecom PJSC
    ------------------------------



  • 13.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 26, 2021 03:40

    @Florin Tene can you share a link where I might find information regarding the upcoming changes within the TMF673?

    Thanks,

    Jan​



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------



  • 14.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Oct 20, 2021 03:43
    Hi Darren,

    We're beginning work on the address API for Openreach and we have similar issue but also have additional properties which we want to add so will be sub-classing the address property to produce something more specific. The base address model is fairly generic and so we need to extend it to also include things which we use in the UK address such as county and dependent thoroughfare, but also include building name and sub building name. In your example, if you look at the address for Riverside House, that is held in the building name.


    ------------------------------
    Steve Ranford-Bragg
    BT Group plc
    ------------------------------



  • 15.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Nov 01, 2021 07:41
    Edited by Florin Tene Nov 01, 2021 07:46

    Hi, 

      Thank you all for the inputs and apologies for my late contribution.

       @Tomáš Hajný, you are right; there are scenarios, especially in the Shipping context, where you might want to capture a delivery point with details regarding and individual/organization without recording them as "party" in the customer domain. For example, when we have one party playing the role of the customer buying products but wants the items delivered to another individual/organization address - like in your example to his workplace. This scenario is handled inside the ShippingOrder API via the "RelatedPartyWithContactInfo", where we can capture an individual/organization with the Address or any other contact point information. In this case, the information is captured only in the context of the shipping process (Order/Customer/Shipping), not necessarily for the generic context of the Address entity.

        @Victor Anfimov articulated the difference between the GeographicAddress and a DeliveryAddress correctly.
          GeographicAddress is in theory being managed by the LocationManagement platform:

    • TAM -> 7.15 - 
    • Location Management provides the required functionality to manage the physical and logical attributes of location data for the service provider. It can include addresses (street, city, state/province, & country), geospatial information (lat/long)

        On the overall, I agree with you both, it doesn't make sense to capture all the "Organisations" as parties if they are not really parties in your space just for the sake of the address-organization relationship - plus it would be a very tedious process.

        In my view (which I think was also raised by @Victor Anfimov above), the organization name can't be considered address information. Still, I understand that in some cases, some CSP might want to capture "additional" information related to an address relevant to them. If they're going to capture "organization-name" or "building color" or whatever else it is up for their internal use-cases - however we need to always keep in mind the bounded context of the "Address" entity and not go wild.

      So, maybe a generic approach that will allow capturing additional information for a particular address is something to be brought up for the API Governance; For this i've raise the AP-3006 today.

      @Jan Lemmermann, yes, the summary of all the latest changes is available here ( https://projects.tmforum.org/wiki/display/AP/Detail+view+on+TMF673) with a summary of them below:

    • AP-2719 - TMF 673 - Geo Address - does not have event for POST address

    • AP-2718 - TMF 673 - Geo Address Validation - swagger not aligned with user guide

    • AP-2656 - Wrong path for subresource href in examples

    • AP-2633 - Conformance update for AddressValidation 

    • AP-2610 - TMF673 - Geographic Address - Enhance with additional operations (Post, Patch, Delete)

    • AP-2485 - TMF673 - Geographic Address - Enhance with countryCode and 

    • AP-1032 - Geographic Address - discrepancy between spec and conformance document

    • AP-2834 - TMF673 - Geographic Address – Enhance with GeographicAddressType

    • AP-2790 - Manage an array of SubUnit in GeographicSubAddress

     In addition to the above, there is also the AP-2999 (BuildingName) which is pending API Governance call and today i've raise the AP-3006 to see what options are available to capture additional information (scenarios presented above)

      @Steve Ranford-Bragg, can you share with us what additional information you want to capture and how your mapping looks like ? I think we need to look at any opportunity to enhance the openAPIs to be a better fit and to keep the level of sub-classing to a minimum. Happy to raise them in the API Governance and get the feedback.  


    Thank you,



    ------------------------------
    Florin Tene
    CityFibre
    ------------------------------



  • 16.  RE: TMF673 - GeographicAddress - Building

    TM Forum Member
    Posted Nov 01, 2021 07:51
    Edited by Steve Ranford-Bragg Nov 01, 2021 07:53
    Hi,

    For my purposes, apart from the building name name and organisation, mostly I don't think these the fields I need are things I'd expect to be added to the base model as they either company or country specific. For example, for the UK address standard we have things such as "double dependent locality" which describes a smaller unit of location such as a business or industrial estate as part of an address or we have an internal classification of the quality of an address such as gold (an address we serve), silver (imported from an external address source) or bronze (created by a customer as part of an order process). I wouldn't expect the TMF to model these and we'd put into what we'd refer to as an "OpenreachGeographicAddress" sub-class extension to the base model.

    ------------------------------
    Steve Ranford-Bragg
    BT Group plc
    ------------------------------



  • 17.  RE: TMF673 - GeographicAddress - Building

    Posted Nov 01, 2021 11:21
    Dear All
    Thanks for all the contributions, very useful to see the thinking.
    I guess we moved on a lot from Darren's original request to have building name for the main address and not just the sub-premises.
    Sorry if me mentioning Organisation Name is a diversion.

    But (!) as a final word from me on this at least. this is what the UK national standard BS7666 2006 parts 1-5 (a standard for geographic referencing and compilation of land and land use gazetteers) states when describing structures located on parcels of land known as "Basic Land and Property Units" (BLPU). Each BLPU has one or more identifiers called a Land or Property Identifier (LPI). Each LPI consists of a

    Primary Addressable Object Name (to identify the main structure).
    Secondary Addressable Object Name (to identify sub premises).
    Post Code/Post Town.
    Street Name  (by reference to the street gazetteer).

    Where does the organisation name come in? This is the definition of the Primary Addressable Object Name.

    The Primary Addressable Object Name (PAON) is the designated premise number, and/or the premise name, where neither of these exist then the PAON is the name of the organisation in occupation, or a description of the addressable object.

    As Victor mentioned.

    "Unlike delivery GeographicalAddress is just a point on the map and should rather describe what's located there."

    But sometimes (in my opinion) the description includes the big name in lights above the building like the Lidl or Aldi in a retail park.

    And the point is that is what the published third party databases to which you are matching these things will contain.

    https://www.agi.org.uk/bs-7666-guidelines/








    ------------------------------
    Derrick Evans
    ------------------------------