# Expanding Responses

In order to reduce the number of requests to the API that your client needs to make, you can use the `expand` query parameter to included nested information in responses.

Whenever a resource references another resource via a URL, you can use the `expand` parameter to replace that URL with a nested representation of the resource. For example, if you request an EVSE, you will get a link to that EVSE's model:


```http
GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": "https://api.ev.energy/v2/evse_models/emod01HN2NJHAJJAQD32QJ4QXTDSGW",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}
```

If you add `?expand=model` you can get the details for the Model at the same time:


```http
GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y?expand=model
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": {
    "id": "emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "name": "BG SyncEV",
    "make": "https://api.ev.energy/v2/evse_makes/emak01HN2NJQRGDQP0GBE1F7R6PB3D",
  },
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}
```

You could also expand the user resource at the same time by adding two instances of the `expand` query param: `?expand=model&expand=user`.

## Nested expansion

The API also supports multiple levels of nesting by chaining field names with `.`s. For example, to get the model and make of an EVSE, you could use `expand=model.make`:


```http
GET https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y?expand=model,make
{
  "id": "evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "url": "https://api.ev.energy/v2/evses/evse01HN2NFV2BBCV0HWP5X7T1905Y",
  "model": {
    "id": "emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "url": "https://api.ev.energy/v2/evse_models/emod01HN2NJHAJJAQD32QJ4QXTDSGW",
    "name": "BG SyncEV",
    "make": {
      "id": "emak01HN2NJQRGDQP0GBE1F7R6PB3D",
      "url": "https://api.ev.energy/v2/evse_makes/emak01HN2NJQRGDQP0GBE1F7R6PB3D",
      "name": "BG"
    },
  },
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
}
```

## Permissions

Expanding a resource requires your token to have the same scopes you would need to make the corresponding request. For example,
to expand `user` on a Vehicle, you need `user:read` as well as `vehicle:read`. Lacking a required scope will result in a 403 error.

## Errors

If you pass a value to `expand` which cannot be expanded (such as the resource's `id`, a field that isn't present, or a recursive nested expansion like `latest_status_log.vehicle`) a 400 Bad Request response will be generated, with a [problem type](/docs/errors) of [http://api.ev.energy/v2/problems/unexpandable-property/](http://api.ev.energy/v2/problems/unexpandable-property/).