openapi: 3.0.1 info: title: Geographic Site Management description: | **This file forms part of Mplify 122.1** This API implements Business Requirements described in Mplify 150 It allows to retrieve a list of Geographic Sites and to get all information for one geographic site. List of supported Use Cases: - Retrieve Service Site List - Retrieve Service Site by Identifier Copyright 2025 Mplify Alliance and its contributors. This file includes content based on the TM Forum Geographic Site Management API (TMF674 v4.0.0) available at https://github.com/tmforum-apis/TMF674_GeographicSite, which is licensed by the TM Forum under the Apache License version 2.0. Such content has been modified by the Mplify Alliance and its contributors. version: 8.0.0 servers: - url: 'https://{serverBase}/mefApi/sonata/geographicSiteManagement/v8/' variables: serverBase: description: The base of Seller's URL. default: mplify.net tags: - name: geographicSite paths: /geographicSite: post: tags: - geographicSite summary: List or find GeographicSite objects description: >- This operation queries for a list of Sites within a GeographicAddress, which can be referenced with an `id` or be found by list of representations (GeographicAddress_Query). operationId: listGeographicSite parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. Reference: Mplify 150 (Sn 8.8) required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. Reference: Mplify 150 (Sn 8.8) required: false schema: type: string - name: offset in: query description: >- Requested index for the start of item to be provided in response requested by the client. Note that the index starts with "0". required: false schema: type: integer format: int32 - name: limit in: query description: >- Requested number of items to be provided in response requested by client required: false schema: type: integer format: int32 requestBody: description: The query parameters for searching for Geographic Sites content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/GeographicSite_Query' required: true responses: '200': description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)' headers: X-Pagination-Throttled: description: > Used to indicate that result page was throttled to maximum possible size and there are additional results that can be fetched schema: type: boolean X-Total-Count: description: > The total number of matching records. E.g. if there are 50 matching records in total, but the request has offset=10 and limit=10, then the X-Total-Count is 50. schema: type: integer X-Result-Count: description: The number of records included in the response schema: type: integer content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/GeographicSite' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '/geographicSite/{id}': get: tags: - geographicSite summary: Retrieves a GeographicSite by ID description: This operation retrieves a GeographicSite entity. operationId: retrieveGeographicSite parameters: - name: id in: path description: Identifier of the GeographicSite required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. Reference: Mplify 150 (Sn 8.8) required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. Reference: Mplify 150 (Sn 8.8) required: false schema: type: string responses: '200': description: 'OK. (https://tools.ietf.org/html/rfc7231#section-6.3.1)' content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/GeographicSite' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '501': description: >- Method not implemented. Used in case Seller is not supporting this operation. content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error501' components: schemas: Error: description: > Standard Class used to describe API response error Not intended to be used directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. type: object properties: reason: description: >- Text that explains the reason for the error. This can be shown to a client user. type: string maxLength: 255 message: description: >- Text that provides mode details and corrective actions related to the error. This can be shown to a client user. type: string referenceError: description: url pointing to documentation describing the error type: string format: uri required: - reason Error400: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body $ref: '#/components/schemas/Error400Code' required: - code type: object description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)' Error400Code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body type: string enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody Error401: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: >- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired $ref: '#/components/schemas/Error401Code' required: - code type: object description: 'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)' Error401Code: description: |- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired type: string enum: - missingCredentials - invalidCredentials Error403: allOf: - $ref: '#/components/schemas/Error' - properties: code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code type: object description: 'Forbidden. (https://tools.ietf.org/html/rfc7231#section-6.5.3)' Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users type: string enum: - accessDenied - forbiddenRequester - tooManyUsers Error404: description: >- Resource for the requested path not found. (https://tools.ietf.org/html/rfc7231#section-6.5.4) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - notFound: A current representation for the target resource not found type: string enum: - notFound required: - code Error422: description: >- Unprocessable entity due to a business validation problem. (https://tools.ietf.org/html/rfc4918#section-11.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) $ref: '#/components/schemas/Error422Code' propertyPath: description: > A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used. Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901). type: string required: - code Error422Code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) type: string enum: - missingProperty - invalidValue - invalidFormat - referenceNotFound - unexpectedProperty - tooManyRecords - otherIssue Error500: description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. type: string enum: - internalError required: - code Error501: description: >- Not Implemented. Used in case Seller is not supporting an optional operation (https://tools.ietf.org/html/rfc7231#section-6.6.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: |- The following error code: - notImplemented: Method not supported by the server type: string enum: - notImplemented required: - code FieldedAddressRepresentation: description: >- A type of Address that has a discrete field and value for each type of boundary or identifier down to the lowest level of detail. For example "street number" is one field, "street name" is another field, etc. type: object properties: streetNr: description: >- Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses. type: string streetNrSuffix: description: >- The first street number suffix (in a street number range) or the suffix for the street number if there is no range type: string streetNrLast: description: Last number in a range of street numbers allocated to an Address type: string streetNrLastSuffix: description: Last street number suffix for a ranged Address type: string streetPreDirection: description: The direction of the street that appears before the Street Name type: string streetName: description: Name of the street or other street type type: string streetType: description: >- The type of street (e.g., alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf) type: string streetPostDirection: description: >- A modifier denoting a relative direction that appears after the Street Name. type: string poBox: description: Number identifying a specific location in a post office. type: string locality: description: >- An area of defined or undefined boundaries within a local authority or other legislatively defined area. type: string city: description: City in which the Address is located. type: string postcode: description: >- A descriptor for a postal delivery area used to speed and simplify the delivery of mail (also known as zip code) type: string postcodeExtension: description: >- The extension used on a postal code. Note: there are different use codes for this attribute depending upon the country. type: string stateOrProvince: description: The State or Province in which the Address is located. type: string countryCode: description: >- Country in which the Address is located, defined using two characters as defined in ISO 3166 type: string minLength: 2 maxLength: 2 subUnit: description: >- The Service Site Sub Unit represented as a list. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A type: array items: $ref: '#/components/schemas/SubUnit' buildingName: description: > The well-known name of a building that is located at this Address (e.g., where there is one Address for a campus). type: string privateStreetNumber: description: Street number on a private street within the Address. type: string privateStreetName: description: >- Private streets internal to a property (e.g., a university) may have internal names that are not recorded by the land title office. type: string language: description: >- The language in which the address is expressed. Based on ISO 639:2023 type: string minLength: 2 maxLength: 2 FormattedAddressRepresentation: description: 'A freeform text representation agreed to by the Buyer and Seller. ' type: object properties: formattedAddress: description: >- A formatted Address Representation that contains a non-fielded address. type: string language: description: >- The language in which the address is expressed. Based on ISO 639:2023 type: string minLength: 2 maxLength: 2 required: - formattedAddress GeographicAddressRef: description: > A reference to a Geographic Address resource available through Address Validation API. type: object properties: href: description: > Hyperlink to the referenced Address. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request. type: string id: description: >- Identifier of the referenced Geographic Address. This identifier is assigned during a successful address validation request (Geographic Address Management API) type: string '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicAddressRef required: - '@type' - id GeographicAddressRefOrQuery: description: >- Allows pointing to a `GeographicAddress` either by reference or by value. type: object discriminator: propertyName: '@type' mapping: GeographicAddressRef: '#/components/schemas/GeographicAddressRef' GeographicAddress_Query: '#/components/schemas/GeographicAddress_Query' oneOf: - $ref: '#/components/schemas/GeographicAddressRef' - $ref: '#/components/schemas/GeographicAddress_Query' GeographicAddress_Query: description: >- A list of representations being a subset of Geographic Address entity. This is to be used when providing a list of representations to validate or search for a Geographic Address type: object properties: fieldedAddressRepresentation: description: A Fielded Address representation type: array items: $ref: '#/components/schemas/FieldedAddressRepresentation' formattedAddressRepresentation: description: A Formatted Address representation type: array items: $ref: '#/components/schemas/FormattedAddressRepresentation' geographicPointRepresentation: description: A Fielded Address representation type: array items: $ref: '#/components/schemas/GeographicPointRepresentation' labelRepresentation: description: A Fielded Address representation type: array items: $ref: '#/components/schemas/LabelRepresentation' '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicAddress_Query minProperties: 2 required: - '@type' GeographicPointRepresentation: description: > A GeographicPointRepresentation defines a geographic point through coordinates. type: object properties: spatialRef: description: >- The spatial reference system used to determine the coordinates. The system used and the value of this field are to be agreed during the onboarding process. type: string latitude: description: The latitude expressed in the format specified by the `spacialRef` type: string longitude: description: The longitude expressed in the format specified by the `spacialRef` type: string elevation: description: The elevation expressed in the format specified by the `spacialRef` type: string required: - latitude - longitude - spatialRef GeographicSite: description: >- A fixed or mobile place at which a Product can be installed. A Site is always associated with a Geographic Address. This association may include Sub-Units describing where precisely within that Geographic Address this particular Geographic Site is located. type: object properties: id: description: Identifier of the Geographic Site unique within the Seller. type: string href: description: Unique reference of the Geographic Site unique within the Seller. type: string place: description: > A Geographic Address described by identifier or by a set of Geographic Address Representations. $ref: '#/components/schemas/GeographicAddressRefOrQuery' name: description: The name for the Service Site. type: string administrativeAuthority: description: >- The name of the company that is the administrative authority (e.g., controls access) for this Service Site. (For example, the building owner) type: string customerName: description: >- The name of the company that is the administrative authority for the space within this Service Site. (For example, the company leasing space in a multi-tenant building). type: string siteRestrictionType: description: > This defines whether a Geographic Site is public or private. public - means that the existence of this Geographic Site is public information. A meet-me-room in a hosted data center facility (where all interconnects between parties take place) is an example of a public Geographic Site. A shared facility in the basement of a multi-tenant business building where all interconnects between parties take place is another example of a public Geographic Site. private - means that the existence of this Geographic Site is on a need-to-know basis. A wiring closet set up inside a customer facility just to connect two parties is an example of a private Geographic Site. For private sites, the Seller does not return any information regarding the existence of this Geographic Site unless it has been established that this Buyer is authorized to obtain this information. $ref: '#/components/schemas/SiteRestrictionType' networkType: description: >- Indicates whether the Seller is owner of the network to which the Service Site is connected or whether that network is owned by a 3rd party. $ref: '#/components/schemas/SiteNetworkType' subUnit: description: >- A list of Sub Units which describes the Service Site detailed position within the Geographic Address. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A type: array items: $ref: '#/components/schemas/SubUnit' '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicSite required: - '@type' - administrativeAuthority - customerName - id - name - networkType - place - siteRestrictionType - subUnit GeographicSite_Query: description: >- A flavor of the `GeographicSite` type to be used in the context of the `listGeographicSite` operation. It does not contain the `id`, `href`, and `@type` attributes and all the remaining, despite `place`, are optional. type: object properties: place: description: > A set of location descriptions, each of which describes where this GeographicSite is located. It is important to note that this is a set because a particular Geographic Site might be described with multiple locations. For example, one Geographic Site might have two Fielded Addresses (for a building on the corner of two streets), two Formatted Addresses, and a Geographic Point. $ref: '#/components/schemas/GeographicAddressRefOrQuery' name: description: The name for the Service Site. type: string administrativeAuthority: description: >- The name of the company that is the administrative authority (e.g., controls access) for this Service Site. (For example, the building owner) type: string customerName: description: >- The name of the company that is the administrative authority for the space within this Service Site. (For example, the company leasing space in a multi-tenant building). type: string siteRestrictionType: description: > This defines whether a Geographic Site is public or private. public - means that the existence of this Geographic Site is public information. A meet-me-room in a hosted data center facility (where all interconnects between parties take place) is an example of a public Geographic Site. A shared facility in the basement of a multi-tenant business building where all interconnects between parties take place is another example of a public Geographic Site. private - means that the existence of this Geographic Site is on a need-to-know basis. A wiring closet set up inside a customer facility just to connect two parties is an example of a private Geographic Site. For private sites, the Seller does not return any information regarding the existence of this Geographic Site unless it has been established that this Buyer is authorized to obtain this information. $ref: '#/components/schemas/SiteRestrictionType' networkType: description: >- Indicates whether the Seller is owner of the network to which the Service Site is connected or whether that network is owned by a 3rd party. $ref: '#/components/schemas/SiteNetworkType' subUnit: description: >- A list of Sub Units which describes the Service Site detailed position within the Geographic Address. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A type: array items: $ref: '#/components/schemas/SubUnit' required: - place LabelRepresentation: description: >- A unique identifier controlled by a generally accepted independent administrative authority that specifies a fixed geographical location. type: object properties: label: description: >- The unique reference to a Geographic Address assigned by the Administrative Authority. type: string administrativeAuthority: description: >- The organization or standard from the organization that administers this Geographic Address Label ensuring it is unique within the Administrative Authority. type: string language: description: 'The language in which the label is expressed. Based on ISO 639:2023' type: string minLength: 2 maxLength: 2 required: - administrativeAuthority - label SiteNetworkType: description: >- Indicates whether the Seller is owner of the network to which the Service Site is connected or whether that network is owned by a 3rd party. type: string enum: - offNet - onNet SiteRestrictionType: description: | This defines whether a Geographic Site is public or private. public - means that the existence of this Geographic Site is public information. A meet-me-room in a hosted data center facility (where all interconnects between parties take place) is an example of a public Geographic Site. A shared facility in the basement of a multi-tenant business building where all interconnects between parties take place is another example of a public Geographic Site. private - means that the existence of this Geographic Site is on a need-to-know basis. A wiring closet set up inside a customer facility just to connect two parties is an example of a private Geographic Site. For private sites, the Seller does not return any information regarding the existence of this Geographic Site unless it has been established that this Buyer is authorized to obtain this information. type: string enum: - public - private SubUnit: description: Allows for sub unit identification type: object properties: subUnitNumber: description: >- The discriminator used for the subunit, often just a simple number but may also be a range. type: string subUnitType: description: >- The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF. type: string required: - subUnitNumber - subUnitType