ATCO Query API

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.
  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:
    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"}'
    geometry:
      name: geometry
      in: query
      required: false
      description: Spatial filter geometry, as JSON or comma-separated envelope/point coordinates.
      schema:
        type: string
    groupByFieldsForStatistics:
      name: groupByFieldsForStatistics
      in: query
      required: false
      description: Comma-separated group-by field list, used with `outStatistics`.
      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
    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
    orderByFields:
      name: orderByFields
      in: query
      required: false
      description: 'Comma-separated `FIELD [ASC|DESC]` list. Layer advertises `supportsOrderBy: true`.'
      schema:
        type: string
    returnCountOnly:
      name: returnCountOnly
      in: query
      required: false
      description: Return only the matching feature count.
      schema:
        type: boolean
        default: false
    outFields:
      name: outFields
      in: query
      required: false
      description: Comma-separated field list, or `*` for all fields.
      schema:
        type: string
        default: '*'
    returnIdsOnly:
      name: returnIdsOnly
      in: query
      required: false
      description: Return only OBJECTIDs of matching features.
      schema:
        type: boolean
        default: false
    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
    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
    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
    returnExtentOnly:
      name: returnExtentOnly
      in: query
      required: false
      description: 'Return only the extent of matching features. Layer advertises `supportsReturningQueryExtent: true`.'
      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
    geometryType:
      name: geometryType
      in: query
      required: false
      schema:
        type: string
        enum:
        - esriGeometryPoint
        - esriGeometryMultipoint
        - esriGeometryPolyline
        - esriGeometryPolygon
        - esriGeometryEnvelope
        default: esriGeometryEnvelope
    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
    objectIds:
      name: objectIds
      in: query
      required: false
      description: Comma-separated OBJECTID list. maxIdsCount is 1,000,000.
      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
    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
    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
  schemas:
    CountResult:
      type: object
      properties:
        count:
          type: integer
          examples:
          - 880623
    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
    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
    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'
    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'
    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
    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
    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
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/