openapi: 3.1.0
info:
  title: ATCO Electric Hosting Capacity Feature Service
  version: '12'
  summary: >-
    DER hosting capacity for ATCO Electric's Alberta distribution system,
    published as a public, anonymously queryable Esri ArcGIS REST feature service.
  description: >-
    ATCO Electric publishes distributed energy resource (DER) hosting capacity for its
    Alberta distribution system as an Esri ArcGIS Online hosted feature service. A single
    polyline feature layer, "Hosting Capacity (KW)" (layer id 0), carries one feature per
    feeder segment with the substation, circuit, phase and the DER capacity in kW that the
    segment can host. An anonymous count query returned 880,623 features and 135 distinct
    substation names on 2026-07-27.


    This OpenAPI document was GENERATED by API Evangelist from the service's own
    self-describing ArcGIS REST descriptors (harvested verbatim to
    openapi/atco-electric-hosting-capacity-featureserver.esri.json and
    openapi/atco-electric-hosting-capacity-layer-0.esri.json) plus live, anonymous probes of
    the running service on 2026-07-27. ATCO publishes no OpenAPI of its own and no API
    documentation page; the parameter set below is the subset of the Esri ArcGIS REST Feature
    Service query specification that this service actually advertises (capabilities "Query")
    and that was exercised successfully against the live endpoint. Nothing here is invented:
    every path, parameter and field is present in the harvested descriptor or was confirmed
    by a live request.


    Access is completely ungated: no API key, no token, no signup, no referer check and no
    licence click-through. `Access-Control-Allow-Origin: *` is returned, so the service is
    directly callable from a browser. maxRecordCount is 1000, so paginate with `resultOffset`
    and `resultRecordCount` and watch `exceededTransferLimit` in the response.


    Note on error semantics: ArcGIS REST returns application errors with HTTP status 200 and
    an `{"error": {...}}` body rather than a 4xx status. See
    errors/atco-problem-types.yml.
  contact:
    name: ATCO Electric
    url: https://electric.atco.com/en-ca/about-us/contact.html
  x-generated-by: API Evangelist enrichment pipeline
  x-generated: '2026-07-27'
  x-method: generated
  x-source:
  - https://services7.arcgis.com/cw2emabghNLkoYlB/arcgis/rest/services/AGO_HostingCapacity/FeatureServer?f=json
  - https://services7.arcgis.com/cw2emabghNLkoYlB/arcgis/rest/services/AGO_HostingCapacity/FeatureServer/0?f=json
externalDocs:
  description: Esri ArcGIS REST API — Feature Service reference (the upstream contract this service implements)
  url: https://developers.arcgis.com/rest/services-reference/enterprise/feature-service/
servers:
- url: https://services7.arcgis.com/cw2emabghNLkoYlB/arcgis/rest/services/AGO_HostingCapacity/FeatureServer
  description: ATCO Electric AGO_HostingCapacity feature service (ArcGIS Online tenant cw2emabghNLkoYlB, org urlKey "ATCO")
tags:
- name: Service
  description: Feature service and feature layer metadata
- name: Query
  description: Read-only queries against the hosting capacity feature layer
security: []
paths:
  /:
    get:
      tags:
      - Service
      operationId: getFeatureServiceInfo
      summary: Get feature service metadata
      description: >-
        Returns the self-describing FeatureServer descriptor — currentVersion, serviceDescription,
        capabilities, maxRecordCount, spatial reference, full extent and the layer list.
      parameters:
      - $ref: '#/components/parameters/f'
      responses:
        '200':
          description: Feature service descriptor, or an ArcGIS error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureServiceInfo'
              examples:
                serviceInfo:
                  summary: AGO Hosting Capacity service descriptor (truncated)
                  value:
                    currentVersion: 12
                    serviceItemId: 7b4d2b3dcecb4a509f34cbfc3587ff3e
                    serviceDescription: AGO Hosting Capacity
                    description: CYME Hosting Capacity Map
                    capabilities: Query
                    maxRecordCount: 1000
                    layers:
                    - id: 0
                      name: Hosting Capacity (KW)
                      type: Feature Layer
                      geometryType: esriGeometryPolyline
  /0:
    get:
      tags:
      - Service
      operationId: getHostingCapacityLayerInfo
      summary: Get hosting capacity feature layer metadata
      description: >-
        Returns the layer 0 descriptor — field definitions, object id field, geometry type,
        extent, drawing info, advanced query capabilities and record-count limits.
      parameters:
      - $ref: '#/components/parameters/f'
      responses:
        '200':
          description: Feature layer descriptor, or an ArcGIS error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureLayerInfo'
  /0/query:
    get:
      tags:
      - Query
      operationId: queryHostingCapacity
      summary: Query hosting capacity feeder segments
      description: >-
        Query the "Hosting Capacity (KW)" layer with a SQL `where` clause, an optional spatial
        filter, and optional statistics. Supports pagination via `resultOffset` /
        `resultRecordCount` (maxRecordCount 1000; `standardMaxRecordCount` 2000, and 32000 when
        `returnGeometry=false`). Set `returnCountOnly=true` for a feature count,
        `returnDistinctValues=true` for a distinct-value list, and `f=geojson` for RFC 7946 GeoJSON.
      parameters:
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/objectIds'
      - $ref: '#/components/parameters/geometry'
      - $ref: '#/components/parameters/geometryType'
      - $ref: '#/components/parameters/inSR'
      - $ref: '#/components/parameters/spatialRel'
      - $ref: '#/components/parameters/outFields'
      - $ref: '#/components/parameters/returnGeometry'
      - $ref: '#/components/parameters/outSR'
      - $ref: '#/components/parameters/orderByFields'
      - $ref: '#/components/parameters/groupByFieldsForStatistics'
      - $ref: '#/components/parameters/outStatistics'
      - $ref: '#/components/parameters/returnDistinctValues'
      - $ref: '#/components/parameters/returnCountOnly'
      - $ref: '#/components/parameters/returnExtentOnly'
      - $ref: '#/components/parameters/returnIdsOnly'
      - $ref: '#/components/parameters/resultOffset'
      - $ref: '#/components/parameters/resultRecordCount'
      - $ref: '#/components/parameters/having'
      - $ref: '#/components/parameters/f'
      responses:
        '200':
          description: >-
            A feature set, a count, a distinct-value set, or an ArcGIS error envelope
            (ArcGIS returns application errors with HTTP 200).
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FeatureSet'
                - $ref: '#/components/schemas/CountResult'
                - $ref: '#/components/schemas/ErrorEnvelope'
              examples:
                count:
                  summary: Total feature count (verified 2026-07-27)
                  value:
                    count: 880623
                invalidWhere:
                  summary: Error envelope returned with HTTP 200
                  value:
                    error:
                      code: 400
                      message: Cannot perform query. Invalid query parameters.
                      details:
                      - "'where' parameter is invalid"
            application/geo+json:
              schema:
                $ref: '#/components/schemas/GeoJSONFeatureCollection'
    post:
      tags:
      - Query
      operationId: queryHostingCapacityByPost
      summary: Query hosting capacity feeder segments (form POST)
      description: >-
        Identical to the GET form, submitted as `application/x-www-form-urlencoded`. Use this
        when the `where` clause or geometry exceeds practical URL length. Verified anonymously
        on 2026-07-27.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            examples:
              bySubstation:
                summary: Count segments on the BONNYVILLE substation (verified — 34,009)
                value:
                  where: "SUB_NAME='BONNYVILLE'"
                  returnCountOnly: true
                  f: json
      responses:
        '200':
          description: >-
            A feature set, a count, or an ArcGIS error envelope.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FeatureSet'
                - $ref: '#/components/schemas/CountResult'
                - $ref: '#/components/schemas/ErrorEnvelope'
  /0/queryTopFeatures:
    get:
      tags:
      - Query
      operationId: queryTopHostingCapacityFeatures
      summary: Query top features per group
      description: >-
        Return the top N features within each group — for example the highest DER capacity
        segment per substation. The layer advertises `supportsTopFeaturesQuery: true`; a `where`
        clause is required in addition to `topFilter`. Verified anonymously on 2026-07-27.
      parameters:
      - $ref: '#/components/parameters/topFilter'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/outFields'
      - $ref: '#/components/parameters/returnGeometry'
      - $ref: '#/components/parameters/resultOffset'
      - $ref: '#/components/parameters/resultRecordCount'
      - $ref: '#/components/parameters/f'
      responses:
        '200':
          description: A feature set of the top features per group, or an ArcGIS error envelope.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/FeatureSet'
                - $ref: '#/components/schemas/ErrorEnvelope'
components:
  parameters:
    f:
      name: f
      in: query
      required: false
      description: >-
        Response format. The service advertises supportedQueryFormats "JSON, geoJSON, PBF";
        `html` and `pjson` are also served by ArcGIS REST.
      schema:
        type: string
        enum: [json, geojson, pbf, pjson, html]
        default: html
    where:
      name: where
      in: query
      required: false
      description: >-
        A standardized SQL WHERE clause over the layer's fields (the layer sets
        `useStandardizedQueries: true`). Use `1=1` for all features.
      schema:
        type: string
      examples:
        all:
          value: 1=1
        bySubstation:
          value: "SUB_NAME='BONNYVILLE'"
        byCapacity:
          value: DER_CAP_KW > 15000
    objectIds:
      name: objectIds
      in: query
      required: false
      description: Comma-separated OBJECTID list. maxIdsCount is 1,000,000.
      schema:
        type: string
    geometry:
      name: geometry
      in: query
      required: false
      description: Spatial filter geometry, as JSON or comma-separated envelope/point coordinates.
      schema:
        type: string
    geometryType:
      name: geometryType
      in: query
      required: false
      schema:
        type: string
        enum:
        - esriGeometryPoint
        - esriGeometryMultipoint
        - esriGeometryPolyline
        - esriGeometryPolygon
        - esriGeometryEnvelope
        default: esriGeometryEnvelope
    inSR:
      name: inSR
      in: query
      required: false
      description: >-
        Spatial reference of the input geometry. The layer's native spatial reference is
        wkid 102185 / latestWkid 3401 (NAD83 / Alberta 3TM ref merid 115 W).
      schema:
        type: string
    spatialRel:
      name: spatialRel
      in: query
      required: false
      description: Spatial relationship to apply. Values taken verbatim from the layer's `supportedSpatialRelationships`.
      schema:
        type: string
        enum:
        - esriSpatialRelIntersects
        - esriSpatialRelContains
        - esriSpatialRelCrosses
        - esriSpatialRelEnvelopeIntersects
        - esriSpatialRelIndexIntersects
        - esriSpatialRelOverlaps
        - esriSpatialRelTouches
        - esriSpatialRelWithin
        - esriSpatialRelDisjoint
        - esriSpatialRelRelation
        default: esriSpatialRelIntersects
    outFields:
      name: outFields
      in: query
      required: false
      description: Comma-separated field list, or `*` for all fields.
      schema:
        type: string
        default: '*'
    returnGeometry:
      name: returnGeometry
      in: query
      required: false
      description: >-
        Include feature geometry. Setting this to false raises the per-request ceiling to
        `standardMaxRecordCountNoGeometry` (32,000).
      schema:
        type: boolean
        default: true
    outSR:
      name: outSR
      in: query
      required: false
      description: Output spatial reference wkid, e.g. 4326 for WGS84.
      schema:
        type: string
    orderByFields:
      name: orderByFields
      in: query
      required: false
      description: "Comma-separated `FIELD [ASC|DESC]` list. Layer advertises `supportsOrderBy: true`."
      schema:
        type: string
    groupByFieldsForStatistics:
      name: groupByFieldsForStatistics
      in: query
      required: false
      description: Comma-separated group-by field list, used with `outStatistics`.
      schema:
        type: string
    outStatistics:
      name: outStatistics
      in: query
      required: false
      description: >-
        JSON array of statistic definitions. Supported statistic types include COUNT, SUM,
        AVG, VAR, STDDEV, MIN, MAX and the percentile family.
      schema:
        type: string
    returnDistinctValues:
      name: returnDistinctValues
      in: query
      required: false
      description: "Return distinct values for `outFields`. Layer advertises `supportsDistinct: true`."
      schema:
        type: boolean
        default: false
    returnCountOnly:
      name: returnCountOnly
      in: query
      required: false
      description: Return only the matching feature count.
      schema:
        type: boolean
        default: false
    returnExtentOnly:
      name: returnExtentOnly
      in: query
      required: false
      description: "Return only the extent of matching features. Layer advertises `supportsReturningQueryExtent: true`."
      schema:
        type: boolean
        default: false
    returnIdsOnly:
      name: returnIdsOnly
      in: query
      required: false
      description: Return only OBJECTIDs of matching features.
      schema:
        type: boolean
        default: false
    resultOffset:
      name: resultOffset
      in: query
      required: false
      description: >-
        Zero-based offset into the result set. Layer advertises `supportsPagination: true`.
        Pair with `resultRecordCount` and always order by a stable field.
      schema:
        type: integer
        minimum: 0
    resultRecordCount:
      name: resultRecordCount
      in: query
      required: false
      description: >-
        Page size. maxRecordCount is 1000; standardMaxRecordCount 2000; 32000 with
        `returnGeometry=false`.
      schema:
        type: integer
        minimum: 1
        maximum: 32000
    having:
      name: having
      in: query
      required: false
      description: "SQL HAVING clause applied to grouped statistics. Layer advertises `supportsHavingClause: true`."
      schema:
        type: string
    topFilter:
      name: topFilter
      in: query
      required: true
      description: >-
        JSON object with `groupByFields`, `topCount` and `orderByFields` selecting the top N
        features per group.
      schema:
        type: string
      example: '{"groupByFields":"SUB_NAME","topCount":1,"orderByFields":"DER_CAP_KW DESC"}'
  schemas:
    FeatureServiceInfo:
      type: object
      description: ArcGIS REST FeatureServer descriptor. Harvested verbatim in openapi/atco-electric-hosting-capacity-featureserver.esri.json.
      properties:
        currentVersion:
          type: number
        serviceItemId:
          type: string
        serviceDescription:
          type: string
        description:
          type: string
        capabilities:
          type: string
          description: Comma-separated capability list. This service advertises "Query" only — it is read-only.
        maxRecordCount:
          type: integer
        maxIdsCount:
          type: integer
        supportedQueryFormats:
          type: string
        supportedExportFormats:
          type: string
        spatialReference:
          $ref: '#/components/schemas/SpatialReference'
        fullExtent:
          $ref: '#/components/schemas/Extent'
        initialExtent:
          $ref: '#/components/schemas/Extent'
        layers:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
              type:
                type: string
              geometryType:
                type: string
        tables:
          type: array
          items:
            type: object
    FeatureLayerInfo:
      type: object
      description: ArcGIS REST Feature Layer descriptor. Harvested verbatim in openapi/atco-electric-hosting-capacity-layer-0.esri.json.
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
        geometryType:
          type: string
        objectIdField:
          type: string
        displayField:
          type: string
        maxRecordCount:
          type: integer
        standardMaxRecordCount:
          type: integer
        standardMaxRecordCountNoGeometry:
          type: integer
        capabilities:
          type: string
        extent:
          $ref: '#/components/schemas/Extent'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldInfo'
    FieldInfo:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        alias:
          type: string
        sqlType:
          type: string
        length:
          type: integer
        nullable:
          type: boolean
        editable:
          type: boolean
    SpatialReference:
      type: object
      properties:
        wkid:
          type: integer
        latestWkid:
          type: integer
    Extent:
      type: object
      properties:
        xmin:
          type: number
        ymin:
          type: number
        xmax:
          type: number
        ymax:
          type: number
        spatialReference:
          $ref: '#/components/schemas/SpatialReference'
    HostingCapacityAttributes:
      type: object
      description: >-
        Attributes of one feeder segment in the "Hosting Capacity (KW)" layer. Field names,
        types, aliases and lengths are taken verbatim from the layer descriptor.
      properties:
        OBJECTID:
          type: integer
          description: System-maintained object id (esriFieldTypeOID), unique and not nullable.
        FEEDER:
          type: [string, 'null']
          maxLength: 200
          description: Feeder / circuit identifier (field alias "CIRCUIT").
          examples: ['700-508']
        PHASE:
          type: [string, 'null']
          maxLength: 200
          description: Phase designation of the segment.
          examples: ['B', 'AB']
        SUB_NAME:
          type: [string, 'null']
          maxLength: 200
          description: Substation name. The layer's displayField. 135 distinct values observed 2026-07-27.
          examples: ['BONNYVILLE']
        SUB_NUM:
          type: [string, 'null']
          maxLength: 200
          description: Substation number.
          examples: ['700S']
        DATELOADED:
          type: [string, 'null']
          maxLength: 200
          description: >-
            Load date of the underlying CYME hosting capacity study, as an unpadded YYYYMMDD
            string (stored as a string field, not a date field).
          examples: ['20251031']
        DER_CAP_KW:
          type: [number, 'null']
          description: Distributed energy resource hosting capacity for the segment, in kilowatts.
          examples: [62.9]
        DER_CAP_KW1:
          type: [number, 'null']
          description: >-
            Second DER capacity field carrying the alias "DER_CAP_KW". Observed equal to
            DER_CAP_KW in sampled features; ATCO publishes no field definitions, so the intended
            distinction is undocumented.
          examples: [62.9]
        PROJECT_AREA:
          type: [string, 'null']
          maxLength: 50
          description: Project area (field alias "PROJ_AREA"). Null in sampled features.
        SE_ANNO_CAD_DATA:
          type: [string, 'null']
          description: ArcSDE annotation CAD blob field (esriFieldTypeBlob). Empty in sampled features.
        Shape__Length:
          type: [number, 'null']
          description: Segment length in metres (geometryProperties.units esriMeters). Read-only.
          examples: [678.11243656856732]
    Feature:
      type: object
      properties:
        attributes:
          $ref: '#/components/schemas/HostingCapacityAttributes'
        geometry:
          type: [object, 'null']
          description: Esri polyline geometry — a `paths` array of coordinate arrays.
          properties:
            paths:
              type: array
              items:
                type: array
                items:
                  type: array
                  items:
                    type: number
    FeatureSet:
      type: object
      properties:
        objectIdFieldName:
          type: string
        uniqueIdField:
          type: object
          properties:
            name:
              type: string
            isSystemMaintained:
              type: boolean
        globalIdFieldName:
          type: string
        geometryType:
          type: string
        spatialReference:
          $ref: '#/components/schemas/SpatialReference'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldInfo'
        exceededTransferLimit:
          type: boolean
          description: >-
            True when more features match than were returned. This is the pagination signal —
            keep advancing `resultOffset` until it is absent or false.
        features:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
    GeoJSONFeatureCollection:
      type: object
      description: RFC 7946 GeoJSON, returned when `f=geojson`. Verified against the live service 2026-07-27.
      properties:
        type:
          type: string
          const: FeatureCollection
        properties:
          type: object
          properties:
            exceededTransferLimit:
              type: boolean
        features:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                const: Feature
              id:
                type: integer
              geometry:
                type: [object, 'null']
              properties:
                $ref: '#/components/schemas/HostingCapacityAttributes'
    CountResult:
      type: object
      properties:
        count:
          type: integer
          examples: [880623]
    QueryRequest:
      type: object
      description: Form-encoded body for the POST form of the query operation.
      properties:
        where:
          type: string
        objectIds:
          type: string
        geometry:
          type: string
        geometryType:
          type: string
        spatialRel:
          type: string
        outFields:
          type: string
        returnGeometry:
          type: boolean
        outSR:
          type: string
        orderByFields:
          type: string
        groupByFieldsForStatistics:
          type: string
        outStatistics:
          type: string
        returnDistinctValues:
          type: boolean
        returnCountOnly:
          type: boolean
        resultOffset:
          type: integer
        resultRecordCount:
          type: integer
        f:
          type: string
    ErrorEnvelope:
      type: object
      description: >-
        ArcGIS REST error envelope. Note that it is returned with HTTP status 200, not a 4xx —
        clients MUST inspect the body for an `error` member rather than relying on the status code.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            details:
              type: array
              items:
                type: string