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

# Pylon

> Show a site's current charging price and how many chargers are free, to drive a price pylon.

A pylon is the physical sign at a site that shows the current charging price and how many spots are free — familiar from fuel stations, and increasingly common at charging sites. By the end of this playbook you'll be able to read both figures from the API and keep them current on the display.

## Before you start

You'll need an [API key](/developers/authentication), and the ID of the [location](/components/charging/locations) the pylon serves. Both figures come from that location: its EVSEs carry their status, and their connectors carry the tariff that sets the price.

## Show the current price

<Steps>
  <Step title="Fetch the location and find its tariff">
    Fetch the site by ID. Each EVSE's connectors carry `tariffIds` — the currently valid tariffs for that connector.

    ```bash theme={null}
    curl https://api.spirii.com/v2/locations/12345 \
      -H "Authorization: Bearer <SPIRII_API_KEY>"
    ```

    ```json theme={null}
    "evses": [
      {
        "status": "AVAILABLE",
        "connectors": [
          { "id": 1, "tariffIds": ["58652fe8-d840-4aa4-bb4f-3ebd944df9d6"] }
        ]
      }
    ]
    ```
  </Step>

  <Step title="Fetch the tariff and read the price">
    Fetch the tariff by that ID:

    ```bash theme={null}
    curl https://api.spirii.com/v2/tariffs/58652fe8-d840-4aa4-bb4f-3ebd944df9d6 \
      -H "Authorization: Bearer <SPIRII_API_KEY>"
    ```

    The price per kWh is the `price` on the price component of type `ENERGY`; the `currency` sits on the tariff. The `price` is exclusive of VAT — apply the component's `vat` if the pylon shows a consumer-facing, VAT-inclusive figure.
  </Step>
</Steps>

<Note>
  A tariff can hold more than one element, each with its own `restrictions` (time of day, day of week, date range). Elements are evaluated top to bottom, and the first whose restrictions match applies — so to show the *current* price, pick the first element whose restrictions are satisfied right now, then read its `ENERGY` component. A tariff with a single, unrestricted element has one price. The structure follows OCPI 2.1.1.
</Note>

## Show charger availability

Fetch the same location and count the EVSEs whose `status` is `AVAILABLE` — that's the number of free charging spots.

```bash theme={null}
curl https://api.spirii.com/v2/locations/12345 \
  -H "Authorization: Bearer <SPIRII_API_KEY>"
```

The `status` on each EVSE is an OCPI value — `AVAILABLE`, `CHARGING`, `BLOCKED`, `OUTOFORDER`, and so on — so a simple count of `AVAILABLE` EVSEs gives the free-spot figure for the display.

## Keep it current

<Tip>
  A single location call returns both the EVSE statuses and the connector `tariffIds`, so one request per refresh covers availability. Tariffs change rarely — fetch each one once and cache it, refetching only when a connector's `tariffIds` change.
</Tip>

* **Poll on a sensible interval** and stay within the [rate limit](/developers/rate-limits) of 120 requests per minute — availability changes far faster than price, so you can refresh it more often.
* **Evaluate tariff restrictions in local time**, so time-of-day pricing flips at the right moment on the display.
* **Fail gracefully.** If a request errors, keep showing the last known values rather than blanking the pylon, and retry with backoff. See [Errors](/developers/errors).

## Related

<CardGroup cols={2}>
  <Card title="Locations" icon="map-pin" href="/components/charging/locations">
    The site, its EVSEs, and their connectors and status.
  </Card>

  <Card title="EVSEs" icon="plug" href="/components/charging/evses-and-connectors">
    EVSE status values and what they mean.
  </Card>
</CardGroup>