> ## 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.

# Bulk availability check



## OpenAPI

````yaml /openapi/emsp-location/openapi.yaml post /emsp/v1/locations/availability
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/availability:
    post:
      tags:
        - Locations
      summary: Bulk availability check
      operationId: locations_check_availability
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckAvailabilityBodyDto'
      responses:
        '200':
          description: Availability counts for each requested location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationAvailabilityResponse'
        '400':
          description: Invalid request body
          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:
    CheckAvailabilityBodyDto:
      type: object
      properties:
        token_id:
          type: string
          description: >-
            End-user token id; resolves through its token group to the reachable
            SUB networks.
        token_group_id:
          type: string
          description: >-
            Token group id (peer to token_id); resolves to its assigned SUB
            networks.
        location_ids:
          description: Location ids to check (1-100).
          type: array
          items:
            type: string
            format: uuid
      required:
        - location_ids
    LocationAvailabilityResponse:
      type: object
      properties:
        locations:
          description: Availability per visible location.
          type: array
          items:
            $ref: '#/components/schemas/LocationAvailabilityItemResponse'
      required:
        - locations
    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
    LocationAvailabilityItemResponse:
      type: object
      properties:
        location_id:
          type: string
          format: uuid
          description: Location identifier.
        available_evses:
          type: number
          description: Number of EVSEs currently in AVAILABLE status.
        total_evses:
          type: number
          description: Total number of EVSEs at the location.
      required:
        - location_id
        - available_evses
        - total_evses
    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
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            emsp:locations:read: Search and view locations, EVSEs, connectors

````