openapi: 3.0.1
info:
  title: Ofcom Connected Nations Mobile API
  description: An API based on Connected Nations Mobile data.
  version: '1.0'
servers:
  - url: https://api-proxy.ofcom.org.uk/mobile
paths:
  '/coverage/{PostCode}':
    get:
      summary: Get mobile provision by postcode
      description: <p>This endpoint will return 0/3/4 ratings for EE/H3/TF/VO mobile providers broken down by Voice/Data and Indoor/Outdoor</p>
      operationId: CoverageByPostCodeGet
      parameters:
        - name: PostCode
          in: path
          description: The postcode of interest
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "<p>Successful operation - mobile provision is returned</p>\r\n<p>The return values represent the following: </p>\r\n    <ul>\r\n        <li> 0 = None (you should not expect coverage) </li>\r\n        <li> 3 = Limited (coverage may be limited)</li>\r\n        <li> 4 = Likely (you are likely to have coverage)</li>\r\n    </ul>\r\n<p> Note that return values 1 and 2 are no longer used.</p>"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileAvailabilityArray'
              example:
                - PostCode: string
                  Availability:
                    - UPRN: 0
                      AddressShortDescription: string
                      PostCode: string
                      EEVoiceOutdoor: 1
                      EEVoiceOutdoorNo4g: 1
                      EEVoiceIndoor: 1
                      EEVoiceIndoorNo4g: 1
                      EEDataOutdoor: 1
                      EEDataOutdoorNo4g: 1
                      EEDataIndoor: 1
                      EEDataIndoorNo4g: 1
                      H3VoiceOutdoor: 1
                      H3VoiceOutdoorNo4g: 1
                      H3VoiceIndoor: 1
                      H3VoiceIndoorNo4g: 1
                      H3DataOutdoor: 1
                      H3DataOutdoorNo4g: 1
                      H3DataIndoor: 1
                      H3DataIndoorNo4g: 1
                      TFVoiceOutdoor: 1
                      TFVoiceOutdoorNo4g: 1
                      TFVoiceIndoor: 1
                      TFVoiceIndoorNo4g: 1
                      TFDataOutdoor: 1
                      TFDataOutdoorNo4g: 1
                      TFDataIndoor: 1
                      TFDataIndoorNo4g: 1
                      VOVoiceOutdoor: 1
                      VOVoiceOutdoorNo4g: 1
                      VOVoiceIndoor: 1
                      VOVoiceIndoorNo4g: 1
                      VODataOutdoor: 1
                      VODataOutdoorNo4g: 1
                      VODataIndoor: 1
                      VODataIndoorNo4g: 1
        '404':
          description: Post Code not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileAvailabilityNotFound'
              example:
                PostCode: string
                ErrorMessage: string
        '500':
          description: General error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralError'
              example:
                ErrorMessage: string
components:
  schemas:
    MobileCoverageValue:
      title: MobileCoverageValue
      type: integer
      description: "States:\n * `0` - None\n * `3` - Limited\n * `4` - Likely"
      format: int
      example: 1
    MobileAvailabilityNotFound:
      title: MobileAvailabilityNotFound
      required:
        - PostCode
        - ErrorMessage
      type: object
      properties:
        PostCode:
          maxLength: 7
          type: string
          description: 'Postcode of address, spaces removed'
        ErrorMessage:
          type: string
          description: A human readable error message
    MobileAvailability:
      title: MobileAvailability
      required:
        - PostCode
        - Availability
      type: object
      properties:
        PostCode:
          maxLength: 7
          type: string
          description: 'Postcode of address, spaces removed'
        Availability:
          type: array
          items:
            $ref: '#/components/schemas/MobileProvision'
    MobileProvision:
      title: MobileProvision
      required:
        - UPRN
        - AddressShortDescription
        - PostCode
        - EEVoiceOutdoor
        - EEVoiceOutdoorNo4g
        - EEVoiceIndoor
        - EEVoiceIndoorNo4g
        - EEDataOutdoor
        - EEDataOutdoorNo4g
        - EEDataIndoor
        - EEDataIndoorNo4g
        - H3VoiceOutdoor
        - H3VoiceOutdoorNo4g
        - H3VoiceIndoor
        - H3VoiceIndoorNo4g
        - H3DataOutdoor
        - H3DataOutdoorNo4g
        - H3DataIndoor
        - H3DataIndoorNo4g
        - TFVoiceOutdoor
        - TFVoiceOutdoorNo4g
        - TFVoiceIndoor
        - TFVoiceIndoorNo4g
        - TFDataOutdoor
        - TFDataOutdoorNo4g
        - TFDataIndoor
        - TFDataIndoorNo4g
        - VOVoiceOutdoor
        - VOVoiceOutdoorNo4g
        - VOVoiceIndoor
        - VOVoiceIndoorNo4g
        - VODataOutdoor
        - VODataOutdoorNo4g
        - VODataIndoor
        - VODataIndoorNo4g
      type: object
      properties:
        UPRN:
          type: integer
          description: Unique Property Reference Number
          format: int32
        AddressShortDescription:
          type: string
          description: 'A compiled address description based on use of the Ordnance Survey AddressBase fields of the form - Building Name, Building Number, Dependent_ThoroughFare'
        PostCode:
          maxLength: 7
          type: string
          description: 'Postcode of address, spaces removed'
        EEVoiceOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEVoiceOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEVoiceIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEVoiceIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEDataOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEDataOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEDataIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        EEDataIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3VoiceOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3VoiceOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3VoiceIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3VoiceIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3DataOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3DataOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3DataIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        H3DataIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFVoiceOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFVoiceOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFVoiceIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFVoiceIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFDataOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFDataOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFDataIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        TFDataIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        VOVoiceOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        VOVoiceOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        VOVoiceIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        VOVoiceIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        VODataOutdoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        VODataOutdoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
        VODataIndoor:
          $ref: '#/components/schemas/MobileCoverageValue'
        VODataIndoorNo4g:
          $ref: '#/components/schemas/MobileCoverageValue'
    GeneralError:
      title: GeneralError
      required:
        - ErrorMessage
      type: object
      properties:
        ErrorMessage:
          type: string
          description: A human readable error message
    MobileAvailabilityArray:
      type: array
      items:
        $ref: '#/components/schemas/MobileAvailability'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    apiKeyQuery:
      type: apiKey
      name: subscription-key
      in: query
security:
  - apiKeyHeader: [ ]
  - apiKeyQuery: [ ]