openapi: 3.2.0
info:
  title: ATCO Electric Hosting Capacity Feature Service Query API
  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
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")
security: []
tags:
- name: Query
  description: Read-only queries against the hosting capacity feature layer
paths:
  /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:
    geometryType:
      name: geometryType
      in: query
      required: false
      schema:
        type: string
        enum:
        - esriGeometryPoint
        - esriGeometryMultipoint
        - esriGeometryPolyline
        - esriGeometryPolygon
        - esriGeometryEnvelope
        default: esriGeometryEnvelope
    geometry:
      name: geometry
      in: query
      required: false
      description: Spatial filter geometry, as JSON or comma-separated envelope/point coordinates.
      schema:
        type: string
    returnCountOnly:
      name: returnCountOnly
      in: query
      required: false
      description: Return only the matching feature count.
      schema:
        type: boolean
        default: false
    outSR:
      name: outSR
      in: query
      required: false
      description: Output spatial reference wkid, e.g. 4326 for WGS84.
      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"}'
    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
    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
    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
    returnExtentOnly:
      name: returnExtentOnly
      in: query
      required: false
      description: 'Return only the extent of matching features. Layer advertises `supportsReturningQueryExtent: true`.'
      schema:
        type: boolean
        default: false
    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
    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
    groupByFieldsForStatistics:
      name: groupByFieldsForStatistics
      in: query
      required: false
      description: Comma-separated group-by field list, used with `outStatistics`.
      schema:
        type: string
    orderByFields:
      name: orderByFields
      in: query
      required: false
      description: 'Comma-separated `FIELD [ASC|DESC]` list. Layer advertises `supportsOrderBy: true`.'
      schema:
        type: string
    having:
      name: having
      in: query
      required: false
      description: 'SQL HAVING clause applied to grouped statistics. Layer advertises `supportsHavingClause: true`.'
      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
    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
    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
    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
    outFields:
      name: outFields
      in: query
      required: false
      description: Comma-separated field list, or `*` for all fields.
      schema:
        type: string
        default: '*'
  schemas:
    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.1124365685673
    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'
    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
    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
    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
    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'
    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
    CountResult:
      type: object
      properties:
        count:
          type: integer
          examples:
          - 880623
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/