openapi: 3.2.0
info:
  title: ROOTE Charging API
  version: 2.0.0
  description: Worldwide live mobility near a coordinate.
servers:
- url: https://api.roote.ai
  description: ROOTE API
tags:
- name: Charging
paths:
  /v1/charging/nearby:
    get:
      operationId: getNearbyEvCharging
      security:
      - bearerAuth: []
      summary: Find nearby EV charging stations
      description: Returns Google Places EV charging stations and connector availability when supplied. Missing availability is never represented as zero. Google attribution is mandatory for consumers.
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          minimum: -90
          maximum: 90
        description: Latitude of query_origin
      - name: lon
        in: query
        required: true
        schema:
          type: number
          minimum: -180
          maximum: 180
        description: Longitude of query_origin
      - name: language
        in: query
        schema:
          type: string
        description: Preferred Google result language
      - name: radius
        in: query
        required: false
        schema:
          type: number
          exclusiveMinimum: 0
          default: 1500
        description: Requested metres; values above 10000 are clamped to 10000
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 20
        description: Requested count; values above the Google Nearby Search maximum of 20 are clamped to 20
      - name: debug
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include safe provider, cache and applied-limit diagnostics
      - name: token
        in: query
        deprecated: true
        schema:
          type: string
        description: Compatibility API token; prefer Authorization Bearer.
      responses:
        '200':
          description: Nearby EV charging results
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - query_origin
                - radius
                - total
                - results
                - attribution
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    - empty
                    - partial
                  message:
                    type: string
                  query_origin:
                    type: object
                    required:
                    - lat
                    - lon
                    properties:
                      lat:
                        type: number
                      lon:
                        type: number
                  radius:
                    type: number
                    maximum: 10000
                  total:
                    type: integer
                    minimum: 0
                  results:
                    type: array
                    maxItems: 20
                    items:
                      type: object
                      required:
                      - id
                      - type
                      - service_type
                      - name
                      - location
                      - distance_meters
                      - attributes
                      - source_id
                      - source_type
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                          const: service
                        service_type:
                          type: string
                          const: charging
                        provider:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                        external_id:
                          type: string
                        name:
                          type: string
                        location:
                          type: object
                          required:
                          - lat
                          - lon
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                        distance_meters:
                          type: integer
                          minimum: 0
                        attributes:
                          type: object
                          required:
                          - google_place_id
                          - types
                          - open_status
                          - charging
                          properties:
                            google_place_id:
                              type: string
                            address:
                              type: string
                            primary_type:
                              type: string
                              const: electric_vehicle_charging_station
                            types:
                              type: array
                              items:
                                type: string
                            open_status:
                              type: string
                              enum:
                              - open
                              - closed
                              - unknown
                            opening_hours:
                              type: array
                              items:
                                type: string
                            google_maps_uri:
                              type: string
                            charging:
                              type: object
                              required:
                              - connectors
                              properties:
                                connector_count:
                                  type: integer
                                  minimum: 0
                                available_count:
                                  type: integer
                                  minimum: 0
                                out_of_service_count:
                                  type: integer
                                  minimum: 0
                                availability_updated_at:
                                  type: string
                                  format: date-time
                                connectors:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                    - type
                                    properties:
                                      type:
                                        type: string
                                        enum:
                                        - J1772
                                        - Type 2
                                        - CHAdeMO
                                        - CCS1
                                        - CCS2
                                        - NACS
                                        - Tesla
                                        - GB/T
                                        - Other
                                      max_kw:
                                        type: number
                                        minimum: 0
                                      count:
                                        type: integer
                                        minimum: 0
                                      available_count:
                                        type: integer
                                        minimum: 0
                                      out_of_service_count:
                                        type: integer
                                        minimum: 0
                                      availability_updated_at:
                                        type: string
                                        format: date-time
                        source_id:
                          type: string
                          const: google
                        source_type:
                          type: string
                          const: partner_api
                  attribution:
                    type: object
                    required:
                    - provider
                    - display_name
                    - required
                    properties:
                      provider:
                        type: string
                        const: Google
                      display_name:
                        type: string
                        const: Google
                      required:
                        type: boolean
                        const: true
                  debug:
                    type: object
                    description: Internal provider diagnostics returned only when debug=true.
                    properties:
                      providers:
                        type: object
                        additionalProperties:
                          type: object
                          required:
                          - status
                          - raw_count
                          - returned_count
                          properties:
                            status:
                              type: string
                              enum:
                              - ok
                              - timeout
                              - error
                              - unauthorized
                              - unavailable
                            raw_count:
                              type: integer
                              minimum: 0
                            returned_count:
                              type: integer
                              minimum: 0
                      provider_calls:
                        type: integer
                      cache:
                        type: string
                        enum:
                        - hit
                        - miss
                        - partial
                      requested_radius:
                        type: number
                      applied_radius:
                        type: number
                      requested_limit:
                        type: integer
                      applied_limit:
                        type: integer
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '401':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '402':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '403':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '429':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
        '503':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
      tags:
      - Charging
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rt_live_...