Skip to main content

Locations

Endpoints for managing locations.

GET Locations​

Retrieve user locations.

GET /v2/hiven/users/:userId/locations
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

[
  {
    "id": "<string>",
    "name": "<string>",
    "coordinates": {
      "latitude": "<number>",
      "longitude": "<number>"
    },
    "countryCode": "<string>",
    "postalCode": "<string>",
    "streetAddress": "<string>",
    "city": "<string>",
    "spotPriceAreaId": "<string>",
    "tariffInfo": {
      "meterId": "<string>", // Optional
      "tariff": "<string>", // Optional
      "electricalUtilityProvider": "<string>" // Optional
    } // Optional
  }
]

Read more

POST Location​

Create new user location.

POST /v2/hiven/users/:userId/locations
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "name": "<string>",
  "coordinates": {
    "latitude": "<number>",
    "longitude": "<number>"
  }
  "countryCode": "<string>",
  "postalCode": "<string>",
  "streetAddress": "<string>",
  "city": "<string>",
  "tariffInfo": {
    "meterId": "<string>", // Optional
    "tariff": "<string>", // Optional
    "electricalUtilityProvider": "<string>" // Optional
  } // Optional
}

Response

{
  "id": "<string>",
  "name": "<string>",
  "coordinates": {
    "latitude": "<number>",
    "longitude": "<number>"
  },
  "countryCode": "<string>",
  "postalCode": "<string>",
  "streetAddress": "<string>",
  "city": "<string>",
  "spotPriceAreaId": "<string>",
  "tariffInfo": {
    "meterId": "<string>", // Optional
    "tariff": "<string>", // Optional
    "electricalUtilityProvider": "<string>" // Optional
  } // Optional
}

Read more

Important note: After updating location if spotPriceAreaId in the response has changed, make sure to update defaultSpotPriceAreaId for all devices of vehicle type.

PUT Location​

Update existing user location.

Important note: Even though it is PUT, it acts as a PATCH allowing partial updates.

PUT /v2/hiven/users/:userId/locations/:locationId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "name": "<string>", // Optional
  "coordinates": {
    "latitude": "<number>",
    "longitude": "<number>"
  } // Optional
  "countryCode": "<string>", // Optional
  "postalCode": "<string>", // Optional
  "streetAddress": "<string>", // Optional
  "city": "<string>", // Optional
  "tariffInfo": {
    "meterId": "<string>", // Optional
    "tariff": "<string>", // Optional
    "electricalUtilityProvider": "<string>" // Optional
  } // Optional
}

Response

{
  "id": "<string>",
  "name": "<string>",
  "coordinates": {
    "latitude": "<number>",
    "longitude": "<number>"
  },
  "countryCode": "<string>",
  "postalCode": "<string>",
  "streetAddress": "<string>",
  "city": "<string>",
  "spotPriceAreaId": "<string>",
  "tariffInfo": {
    "meterId": "<string>", // Optional
    "tariff": "<string>", // Optional
    "electricalUtilityProvider": "<string>" // Optional
  } // Optional
}

Read more

DELETE Location​

Delete existing user location.

DELETE /v2/hiven/users/:userId/locations/:locationId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

""

Read more