MEF Geographic Address API

openapi: 3.2.0
info:
  title: Mef Geographic Address API
  version: '1.0'
  description: 'Operations tagged geographicAddress across 2 of this provider''s published API definitions: mef-lso-cantata-geographic-address-management-openapi.yml, mef-lso-sonata-geographic-address-management-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{serverBase}/mefApi/cantata/geographicAddressManagement/v2/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
- url: https://{serverBase}/mefApi/sonata/geographicAddressManagement/v8/
  variables:
    serverBase:
      description: The base of Seller's URL.
      default: mplify.net
tags:
- name: geographicAddress
paths:
  /geographicAddress/{id}:
    get:
      tags:
      - geographicAddress
      summary: Retrieves a GeographicAddress by ID
      description: This operation retrieves a GeographicAddress entity.
      operationId: retrieveGeographicAddress
      parameters:
      - name: id
        in: path
        description: Identifier of the GeographicAddress
        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.
        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.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/GeographicAddress'
        '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'
    servers:
    - url: https://{serverBase}/mefApi/cantata/geographicAddressManagement/v2/
      variables:
        serverBase:
          description: The base of Seller's URL.
          default: mplify.net
components:
  schemas:
    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
    GeographicPointRepresentation:
      description: 'A type of Representation where coordinates (latitude, longitude and sometimes elevation) are used to specify a particular place on Earth.

        '
      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
    LabelRepresentation:
      description: A type of Geographic Address Representation that is a unique combination of label and Administrative Authority (any organization that distributes labels) that controls assignment of the label and that specifies either a place which may or may not be fixed on Earth.It can be used to identify things that do not have a static Address, such as airplanes or ships
      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 Label ensuring it is unique within the Administrative Authority.
          type: string
        language:
          description: The language in which the label is expressed. It MUST use the ISO 639:2023 two letter code'
          type: string
          minLength: 2
          maxLength: 2
      required:
      - administrativeAuthority
      - label
    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
    GeographicAddress:
      description: A place on Earth, which may or may not be fixed, described using one or more Geographic Address Representations.
      type: object
      properties:
        id:
          description: Unique identifier of the place
          type: string
        href:
          description: Unique reference of the place
          type: string
        hasPublicSite:
          description: This attribute specifies if public sites exist at the GeographicAddress
          $ref: '#/components/schemas/TrueFalseUnknown'
        allowsNewSite:
          description: This attribute specifies if a Buyer must use one of the known existing Sites at this location for any Products delivered to this Address.
          $ref: '#/components/schemas/TrueFalseUnknown'
        fieldedAddressRepresentation:
          description: A list of Fielded Address representations
          type: array
          items:
            $ref: '#/components/schemas/FieldedAddressRepresentation'
        formattedAddressRepresentation:
          description: A list of Formatted Address representations
          type: array
          items:
            $ref: '#/components/schemas/FormattedAddressRepresentation'
        geographicPointRepresentation:
          description: A list of Geographic Point Address representations
          type: array
          items:
            $ref: '#/components/schemas/GeographicPointRepresentation'
        labelRepresentation:
          description: A list of Label Address representations
          type: array
          items:
            $ref: '#/components/schemas/LabelRepresentation'
        '@type':
          description: Used to unambiguously designate the class type when using `oneOf`
          type: string
          enum:
          - GeographicAddress
      required:
      - allowsNewSite
      - hasPublicSite
      - id
      - '@type'
    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)
    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 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. It MUST use the ISO 639:2023 two letter code 639:2023
          type: string
          minLength: 2
          maxLength: 2
    FormattedAddressRepresentation:
      description: A type of Representation using single string based on local postal addressing conventions.
      type: object
      properties:
        formattedAddress:
          description: A string containing the address representation
          type: string
        language:
          description: The language in which the address is expressed.  It MUST use the ISO 639:2023 two letter code
          type: string
          minLength: 2
          maxLength: 2
      required:
      - formattedAddress
    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
    TrueFalseUnknown:
      description: An enumeration used to represent one of three states
      type: string
      enum:
      - 'true'
      - 'false'
      - unknown
    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)
    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
    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
    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
    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 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
x-refined-from:
- mef-lso-cantata-geographic-address-management-openapi.yml
- mef-lso-sonata-geographic-address-management-openapi.yml