Ofcom postcode connectivity profile

arazzo: 1.0.1
info:
  title: Ofcom postcode connectivity profile
  version: 1.0.0
  description: >-
    Build a complete connectivity picture for one UK postcode by calling both Ofcom
    Connected Nations APIs — fixed broadband availability and mobile coverage across
    all four UK operators — and joining the two premises-level result sets on UPRN.
    Ofcom exposes no combined operation, so this stitching is the consumer's job;
    this workflow is that job written down. Each API needs its own approved Azure
    APIM subscription key.
sourceDescriptions:
- name: coverageApi
  url: ../openapi/ofcom-coverage-api-openapi.yml
  type: openapi
workflows:
- workflowId: postcode-connectivity-profile
  summary: Fetch fixed and mobile coverage for a UK postcode and join on UPRN.
  description: >-
    Two independent read-only lookups against the same postcode. Both are safe to
    retry; neither has a request body or any parameter other than the postcode.
  inputs:
    type: object
    required:
    - postCode
    properties:
      postCode:
        type: string
        description: >-
          UK postcode, uppercase with whitespace removed, e.g. SW1A1AA. This is the
          only input either API accepts.
        example: SW1A1AA
  steps:
  - stepId: fixed-coverage
    description: >-
      Predicted fixed broadband availability for every premises in the postcode.
      Speed fields use -1 as the "no prediction available" sentinel.
    operationId: $sourceDescriptions.coverageApi.CoverageByPostCodeGet
    parameters:
    - name: PostCode
      in: path
      value: $inputs.postCode
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      fixedPostCode: $response.body#/PostCode
      fixedAvailability: $response.body#/Availability
  - stepId: mobile-coverage
    description: >-
      Predicted mobile coverage for the same postcode across EE, H3 (Three),
      TF (Virgin Media O2) and VO (Vodafone). Note this API returns an ARRAY of
      postcode envelopes, unlike the broadband API.
    operationId: $sourceDescriptions.coverageApi.CoverageByPostCodeGet
    parameters:
    - name: PostCode
      in: path
      value: $inputs.postCode
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      mobileAvailability: $response.body#/0/Availability
  outputs:
    postCode: $inputs.postCode
    fixedAvailability: $steps.fixed-coverage.outputs.fixedAvailability
    mobileAvailability: $steps.mobile-coverage.outputs.mobileAvailability
x-apievangelist:
  generated: '2026-07-25'
  method: generated
  operationIds_verified: true
  note: >-
    Both steps use the operationId CoverageByPostCodeGet, which exists verbatim in
    both source specs — they are distinguished only by sourceDescription and base
    URL. Joining the two result sets on UPRN happens client-side after the workflow.