> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spirii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search and filter locations



## OpenAPI

````yaml /openapi/emsp-location/openapi.yaml get /emsp/v1/locations
openapi: 3.0.0
info:
  title: Spirii EMMS - Location Discovery API
  description: Real-time charging locations, EVSE availability, and geospatial search
  version: v1
  contact: {}
servers:
  - url: https://api.spirii.com
    description: Production
security:
  - OAuth2ClientCredentials:
      - emsp:locations:read
tags:
  - name: Locations
    description: Location discovery and search operations
paths:
  /emsp/v1/locations:
    get:
      tags:
        - Locations
      summary: Search and filter locations
      operationId: locations_list
      parameters:
        - name: after
          required: false
          in: query
          description: >-
            Cursor to start fetching records after — the `pagination.end_cursor`
            of a previous response. Omit it to fetch the first page, and stop
            paging once `pagination.has_next` is false. Sending it empty is a
            400: an empty cursor is a broken cursor, not a request for the first
            page.
          schema:
            minLength: 1
            type: string
        - name: limit
          required: false
          in: query
          description: Results per page (1–200)
          schema:
            default: 50
            type: number
        - name: token_id
          required: false
          in: query
          description: >-
            End-user token id; resolves through its token group to the reachable
            SUB networks.
          schema:
            type: string
        - name: token_group_id
          required: false
          in: query
          description: >-
            Token group id (peer to token_id); resolves to its assigned SUB
            networks.
          schema:
            type: string
        - name: start_charging_capability
          required: false
          in: query
          description: >-
            Keep only locations with an EVSE usable with this start-charging
            method. `RFID` matches a location with at least one EVSE exposing an
            RFID reader; `APP` matches one with an EVSE that can be
            remote-started. Existential (any EVSE) and availability-agnostic
            (occupied or faulted EVSEs still count).
          schema:
            type: string
            enum:
              - RFID
              - APP
        - name: vehicle_types
          required: false
          in: query
          description: >-
            Keep only locations with an EVSE that fits any of these vehicle
            types. Values are the OCPI VehicleType enum. Matches a location with
            at least one EVSE advertising ANY listed value (multi-value is OR).
            Existential (any EVSE) and availability-agnostic (occupied or
            faulted EVSEs still count).
          schema:
            type: array
            items:
              type: string
              enum:
                - MOTORCYCLE
                - PERSONAL_VEHICLE
                - PERSONAL_VEHICLE_WITH_TRAILER
                - VAN
                - SEMI_TRACTOR
                - RIGID
                - TRUCK_WITH_TRAILER
                - BUS
                - DISABLED
        - name: cpo_ids
          required: false
          in: query
          description: >-
            Filter by CPO operator id (eMI3, e.g. `DK*SPI`). Matches any listed
            value.
          schema:
            type: array
            items:
              type: string
        - name: countries
          required: false
          in: query
          description: Filter by country code. Matches any listed value.
          schema:
            type: array
            items:
              type: string
        - name: latitude
          required: false
          in: query
          description: Center latitude for a geo-distance radius search.
          schema:
            type: number
        - name: longitude
          required: false
          in: query
          description: Center longitude for a geo-distance radius search.
          schema:
            type: number
        - name: radius
          required: false
          in: query
          description: Search radius in metres, 100-50000 (requires latitude + longitude).
          schema:
            type: number
        - name: bounding_box
          required: false
          in: query
          description: >-
            Viewport as `SW_lat,SW_lng,NE_lat,NE_lng` (south-west then
            north-east corner). Alternative to the latitude/longitude/radius
            search — the two are mutually exclusive.
          schema:
            example: 55.6,12.5,55.7,12.6
            type: string
        - name: connector_types
          required: false
          in: query
          description: >-
            Filter by connector standard (e.g. `IEC_62196_T2`). Matches a
            location with at least one connector of ANY listed standard
            (multi-value is OR). An unrecognised standard is a 400, not an empty
            page.
          schema:
            type: array
            items:
              type: string
              enum:
                - CHADEMO
                - CHAOJI
                - DOMESTIC_A
                - DOMESTIC_B
                - DOMESTIC_C
                - DOMESTIC_D
                - DOMESTIC_E
                - DOMESTIC_F
                - DOMESTIC_G
                - DOMESTIC_H
                - DOMESTIC_I
                - DOMESTIC_J
                - DOMESTIC_K
                - DOMESTIC_L
                - DOMESTIC_M
                - DOMESTIC_N
                - DOMESTIC_O
                - GBT_AC
                - GBT_DC
                - IEC_60309_2_single_16
                - IEC_60309_2_three_16
                - IEC_60309_2_three_32
                - IEC_60309_2_three_64
                - IEC_62196_T1
                - IEC_62196_T1_COMBO
                - IEC_62196_T2
                - IEC_62196_T2_COMBO
                - IEC_62196_T3A
                - IEC_62196_T3C
                - MCS
                - NEMA_10_30
                - NEMA_10_50
                - NEMA_14_30
                - NEMA_14_50
                - NEMA_5_20
                - NEMA_6_30
                - NEMA_6_50
                - OTHER
                - PANTOGRAPH_BOTTOM_UP
                - PANTOGRAPH_TOP_DOWN
                - SAE_J3400
                - TESLA_R
                - TESLA_S
        - name: min_power
          required: false
          in: query
          description: >-
            Minimum connector power in watts; matches locations with a connector
            at or above it.
          schema:
            type: number
        - name: availability
          required: false
          in: query
          description: >-
            Keep only locations with an AVAILABLE / UNAVAILABLE EVSE; ALL
            (default) applies no filter.
          schema:
            type: string
            enum:
              - AVAILABLE
              - UNAVAILABLE
              - ALL
        - name: q
          required: false
          in: query
          description: >-
            Free-text search over name, city, postal code, and country. Filters;
            does not re-rank.
          schema:
            type: string
        - name: sort_by
          required: false
          in: query
          description: >-
            Property to sort by; defaults to `created_at`. `distance` requires
            latitude + longitude.
          schema:
            type: string
            enum:
              - created_at
              - last_updated
              - name
              - distance
        - name: sort_direction
          required: false
          in: query
          description: Sort direction.
          schema:
            default: asc
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Paginated list of locations matching the search filters.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedEnvelope'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/LocationReadResponse'
        '400':
          description: Invalid query parameters
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailDto'
        '401':
          description: Missing or invalid credentials
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailDto'
        '403':
          description: Insufficient scope
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetailDto'
components:
  schemas:
    PaginatedEnvelope:
      type: object
      properties:
        pagination:
          description: Pagination state for this page.
          allOf:
            - $ref: '#/components/schemas/PaginationMetaResponse'
        next_cursor:
          type: string
          nullable: true
          example: null
          deprecated: true
          description: 'Deprecated: use `pagination.end_cursor`.'
        has_next:
          type: boolean
          example: false
          deprecated: true
          description: 'Deprecated: use `pagination.has_next`.'
      required:
        - pagination
        - next_cursor
        - has_next
    LocationReadResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Canonical location id.
        cpo_id:
          type: string
          description: CPO id (eMI3, e.g. `DK*SPI`).
        source_id:
          type: string
          description: Operator's own id for the location.
        name:
          type: string
          description: Location name.
        address:
          $ref: '#/components/schemas/AddressReadResponse'
        parking_type:
          type: string
          enum:
            - ALONG_MOTORWAY
            - ON_DRIVEWAY
            - ON_STREET
            - OTHER
            - PARKING_GARAGE
            - PARKING_LOT
            - UNDERGROUND_GARAGE
            - UNKNOWN
        access_type:
          type: string
          enum:
            - PRIVATE
            - PUBLIC
            - RESTRICTED
        facilities:
          description: Location facilities.
          type: array
          items:
            type: string
        evses:
          description: The location EVSEs (each with its connectors).
          type: array
          items:
            $ref: '#/components/schemas/EvseReadResponse'
        last_updated:
          type: string
          format: date-time
          description: Last-update timestamp (UTC).
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (UTC).
      required:
        - id
        - cpo_id
        - source_id
        - name
        - address
        - evses
        - last_updated
        - created_at
    ProblemDetailDto:
      type: object
      properties:
        type:
          type: string
          example: about:blank
          description: >-
            URI identifying the problem type (about:blank until the docs site is
            live)
        title:
          type: string
          example: Tenant not found
        status:
          type: number
          example: 404
        detail:
          type: string
          example: No tenant exists with id 0192...c3.
        instance:
          type: string
          example: /v1/tenant/profile
        code:
          type: string
          example: tenant_not_found
          description: Stable machine-readable error code
        trace_id:
          type: string
          example: abc123def456
          description: Correlation id; matches dd.trace_id in Datadog
        timestamp:
          type: string
          example: '2026-06-10T09:30:00.000Z'
          format: date-time
        errors:
          description: Field-level validation errors (validation failures only)
          type: array
          items:
            $ref: '#/components/schemas/ProblemFieldErrorDto'
      required:
        - type
        - title
        - status
        - detail
        - instance
        - code
        - trace_id
        - timestamp
    PaginationMetaResponse:
      type: object
      properties:
        end_cursor:
          type: string
          nullable: true
          example: null
          description: >-
            Cursor for the end of the current page. Pass it back as `after` to
            fetch the next page; null on the last page.
        has_next:
          type: boolean
          example: false
          description: Whether there are more records to fetch.
      required:
        - end_cursor
        - has_next
    AddressReadResponse:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        postal_code:
          type: string
        country:
          type: string
          description: Country code.
        coordinates:
          $ref: '#/components/schemas/CoordinatesReadResponse'
        time_zone:
          type: string
      required:
        - address
        - city
        - postal_code
        - country
        - coordinates
        - time_zone
    EvseReadResponse:
      type: object
      properties:
        uid:
          type: string
          description: EVSE uid (OCPI natural key, unique within the location).
        evse_id:
          type: string
          description: OCPI EVSE id (e.g. `DK*SPI*E001*1`).
        status:
          type: string
          enum:
            - AVAILABLE
            - BLOCKED
            - CHARGING
            - INOPERATIVE
            - OUTOFORDER
            - PLANNED
            - REMOVED
            - RESERVED
            - UNKNOWN
          description: Current EVSE status.
        capabilities:
          description: OCPI capabilities (e.g. RFID_READER, REMOTE_START_STOP_CAPABLE).
          type: array
          items:
            type: string
        connectors:
          description: The EVSE connectors.
          type: array
          items:
            $ref: '#/components/schemas/ConnectorReadResponse'
      required:
        - uid
        - evse_id
        - status
        - connectors
    ProblemFieldErrorDto:
      type: object
      properties:
        field:
          type: string
          example: workspace_id
        code:
          type: string
          example: is_uuid
        message:
          type: string
          example: workspace_id must be a UUID
      required:
        - field
        - code
        - message
    CoordinatesReadResponse:
      type: object
      properties:
        latitude:
          type: string
          description: Latitude (decimal-degree string, canonical shape).
        longitude:
          type: string
          description: Longitude (decimal-degree string, canonical shape).
      required:
        - latitude
        - longitude
    ConnectorReadResponse:
      type: object
      properties:
        id:
          type: string
          description: Connector id (OCPI, unique within the EVSE).
        standard:
          type: string
          enum:
            - CHADEMO
            - CHAOJI
            - DOMESTIC_A
            - DOMESTIC_B
            - DOMESTIC_C
            - DOMESTIC_D
            - DOMESTIC_E
            - DOMESTIC_F
            - DOMESTIC_G
            - DOMESTIC_H
            - DOMESTIC_I
            - DOMESTIC_J
            - DOMESTIC_K
            - DOMESTIC_L
            - DOMESTIC_M
            - DOMESTIC_N
            - DOMESTIC_O
            - GBT_AC
            - GBT_DC
            - IEC_60309_2_single_16
            - IEC_60309_2_three_16
            - IEC_60309_2_three_32
            - IEC_60309_2_three_64
            - IEC_62196_T1
            - IEC_62196_T1_COMBO
            - IEC_62196_T2
            - IEC_62196_T2_COMBO
            - IEC_62196_T3A
            - IEC_62196_T3C
            - MCS
            - NEMA_10_30
            - NEMA_10_50
            - NEMA_14_30
            - NEMA_14_50
            - NEMA_5_20
            - NEMA_6_30
            - NEMA_6_50
            - OTHER
            - PANTOGRAPH_BOTTOM_UP
            - PANTOGRAPH_TOP_DOWN
            - SAE_J3400
            - TESLA_R
            - TESLA_S
          description: Connector standard.
        format:
          type: string
          enum:
            - CABLE
            - SOCKET
          description: Cable or socket.
        power_type:
          type: string
          enum:
            - AC_1_PHASE
            - AC_3_PHASE
            - DC
          description: AC single/three phase or DC.
        max_electric_power:
          type: number
          description: Maximum electric power in watts.
      required:
        - id
        - standard
        - format
        - power_type
        - max_electric_power
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            emsp:locations:read: Search and view locations, EVSEs, connectors

````