Geosearch

Geosearch API allow to:

• List locations for specified coordinates and distance radius
• Aggregate locations into clusters, for faster response and easier display

Every caller to the Drive APIs Geosearch gets the same results (there are no per-partner exclusions) and all of those are available for the user to charge at.

Geosearch radius - POST

Endpoint: /v1/geosearch/radius

API Reference

Parameters:

• latitude (string, required) - (N58°30' is represented as 58.5)
• longitude (string, required) - (E014°45' is represented as 14.75)
• distance (integer, optional) - in meters (default: 3000m)
• limit (integer, optional) - Max number of locations returned in the response (doesn't apply when aggregation is enabled) (default: 300, max: 300)
• aggregate (boolean, optional, default false) - If true, the results will be aggregated. For large radius it makes the response much faster. (Explained more thoroughly in Aggregation)
• aggregationPrecision (integer, optional) - Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.

Request body:

• filters (object, optional) - available filters and details in Filtering
• options (object, optional)
  • filterEvsesAndConnectors (boolean, optional) - see Options prior to use

Example body:

{
  "filters": {
    "locationStatuses": [
      "AVAILABLE"
    ],
    "capabilities": [
      "REMOTE_START_STOP_CAPABLE"
    ],
    "powerType": "AC",
    "open247": true
  },
  "options": {
    "filterEvsesAndConnectors": true
  }
}

Response fields:

• locations (array, required) - contains all locations returned or an empty array. Location object is described in Location response section. The array limited to 300 locations.
• aggregates (optional array) - only returned if aggregate was set to true in query
  • coordinates - the aggregated coordinates
    • latitude (string)
    • longitude (string)
  • count (number) - number of location returns based on aggregation

Example response:

200 - OK

{
  "locations": [<see Location Response example>],
  "aggregates": [
    {
      "coordinates": {
        "latitude": "51.04759896174073",
        "longitude": "3.7299439776688814"
      },
      "count": 2
    }
  ]
}

Error responses:

• 400 - The provided query parameters or body is invalid.
• 500 - Internal server error.

Geosearch route - POST

This endpoint allows to search for chargers along a route just by passing a set of points that this route consists of.
Additionally, a width of the search from the specified route can be provided.

Endpoint: /v1/geosearch/route

API Reference

Parameters:

• width (integer) - width over the center of the route, in meters. 0.5 of the width on each side.
• limit (integer, optional) - Max number of locations returned in the response (doesn't apply when aggregation is enabled) (default: 300, max: 300)
• aggregate (boolean, optional, default false) - If true, the results will be aggregated. For large radius it makes the response much faster. (Explained more thoroughly in Aggregation)
• aggregationPrecision (integer, optional) - Value between 2 and 9. The bigger value is, the smaller is the cell size of the grid for aggregation. If not passed, a default value, based on radius, is assumed.

Request body:

• points (array of objects, optional) - an array of objects containing latitude and longitude that creates a route.
• filters (object, optional) - available filters and details in Filtering
• options (object, optional)
  • filterEvsesAndConnectors (boolean, optional) - see Options prior to use

Example body:

{
  "points": [
    {
        "latitude": "58.1",
        "longitude": "13.3"
    },
    {
        "latitude": "58.0",
        "longitude": "13.295"
    }
  ],
  "filters": {
    "connectorStandards": [
      "3PinSquare"
    ],
    "locationStatuses": [
      "AVAILABLE"
    ],
    "capabilities": [
      "REMOTE_START_STOP_CAPABLE"
    ],
    "power": 20000,
    "powerType": "AC",
    "open247": true
  }
}

Response fields:

• locations (array, required) - contains all locations returned or an empty array. Location object is described in Location response section. The array limited to 300 locations.
• aggregates (optional array) - only returned if aggregate was set to true in query
  • coordinates - the aggregated coordinates
    • latitude (string)
    • longitude (string)
  • count (number) - number of location returns based on aggregation

Example response:

200 - OK

{
  "locations": [<see Location Response example>],
  "aggregates": [
    {
      "coordinates": {
        "latitude": "51.04759896174073",
        "longitude": "3.7299439776688814"
      },
      "count": 2
    }
  ]
}

Error responses:

• 400 - The provided query parameters, route parameters or body is invalid.
• 500 - Internal server error.

Get location by id - GET

Endpoint: /v1/locations/{locationId}

This endpoint allows to get a location by its id, to know the location id you first need to get locations via another endpoint (for example radius or batch).
The location returned will contain the prices for each of its connectors. You can decide how to look up prices by specifying a customer:

• /v1/locations/{locationId}?userId=b5d00e95-b998-4a33-9210-84777f4cb4f9 returns the prices specific to the user provided, if the user has no specific prices, then the default prices are returned.
• /v1/locations/{locationId}?keyIdentifier=24102023153030 returns the prices specific to the charging key represented by the keyIdentifier provided, if the chargingKey has no specific prices, then the default prices are returned.
• /v1/locations/{locationId}?fleetId=YBnJAbWbja returns the prices specific to the fleet provided, if the fleet has no specific prices, then the default prices are returned.
• /v1/locations/{locationId} returns the default prices

API Reference

Parameters:

• locationId (string, required, path) - Location id to retrieve
• userId (string, optional, query) - The id of a user, will be used to look up specific prices for this user
• keyIdentifier (string, optional, query) - The keyIdentifier of a chargingKey, will be used to look up specific prices for this chargingKey
• fleetId (string, optional, query) - The id of a fleet organization, will be used to look up specific prices for this fleet
• language (string, optional, query) - 2-letter language code, in which the pricing description should be returned (English by default)

⚠️ Only one of userId, keyIdentifier, fleetId can be provided in a single request. If more than one are provided, the endpoint will return 400 BAD_REQUEST

Response fields:

• location (required) - Location object described in Location response
  

Example response:

200 - OK

{
  <see Location Response example>
}

Error responses:

• 404 - Location not found
• 500 - Internal Server Error

Locations batch - GET

Endpoint: /v1/locations/batch

This endpoint allows to get all the locations available to you one page at a time.
Locations are returned sorted by when they have been last updated (last_updated field) ascending, meaning the most recently updated location appears last in the result.

The most efficient way to use this endpoint is to:

1. do a FULL PULL
   1. issue a request to /v1/locations/batch that will return the first page of locations and a cursor
   2. continue asking for more locations calling /v1/locations/batch?cursor=<cursor_from_previous_request>, where cursor_from_previous_request is the cursor returned by the previous request, until the endpoint doesn't return a new cursor, that is the indication there are no more locations to get.
2. after the FULL PULL (1) do incremental DELTA PULLS by specifying the last_updated parameter /v1/locations/batch?last_updated=2024-05-27T10:44:48.123Z (the endpoint will only return locations that have been updated after last_updated). The pagination logic (cursor) should be used for DELTA PULLs as well.
   1. Since the locations are returned in ascending order, you can record the last_updated value of the last location in the last page. That is the point in time when you last were in-sync with location data. You can pass that value as last_updated parameter to the next DELTA PULL. This will guarantee you always receive all updates.

You'd need a single FULL PULL when you first set up the integration, after that only regular DELTA PULLS would be required. You can still perform FULL PULLs later, for example in case you think you are out-of-sync.
You can use the cursor to recover from failures during the PULL process, for example, if the process crashes after 500 pages, you can start from where you left of by issuing the cursor returned by the last page you successfully processed.

API Reference

Parameters:

• page_size (number, optional, max 500) - used to set page size value
• last_updated (ISO date, optional) - when set, only locations updated after this value are returned. example 2024-05-27T10:44:48Z
• countries (string, optional) - one or more ISO-alpha3 country codes. example DEU or DEU,FRA. When this is set only locations in those countries will be returned.
• power_type (string, optional) - when set, only locations having at least one connector with this power_type are returned. possible values: AC or DC.
• cursor (string, optional) - the cursor pointing to the next page:
  • omit when you are requesting the first page
  • pass the value you received in the response (see below) to fetch the next page.

Response fields

• locations (array, required) - contains each location returned or an empty array. Location elements described in Location response
• cursor (string, optional) - the cursor pointing to the next page, when missing it means there are no more pages to fetch.

Example response:

200 - OK

{
  "locations": [<see Location Response example>],
  "cursor": "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFmJ1VVhLdGllUTR5alJXZXN3eTQ3OFEAAAAAAAbnCxYtcG04T296bVR6eWZENXhDUFQzcHBB"
}

Error responses:

• 400 - The provided query parameters, route parameters or body is invalid.
• 500 - Internal server error.

Operators list - GET

Endpoint: /v1/locations/operators

Returns a list of Charging Point Operators which chargers can be returned from geosearch endpoints. Ids returned here can be used as a filter in geosearch endpoint.

Fetch first page without providing any cursor. Use cursor provided in response of each page to get next pages.
Last page is empty and has no cursor.

Parameters:

• cursor (string, optional) - the cursor pointing to the next page. Omit when asking for first page.

Response fields

• operators (array) - list of operator
• id - (integer) this operator id can be used in 'operatorIds' geosearch filter.
• name - (string) user-friendly operator name. Can be the same for multiple ids.
• externalId - (string, optional) the operator's external id (e.g. "DE*ABC")
• cursor (string, optional) - the cursor pointing to the next page, when missing it means there are no more pages to fetch.

Example response:

200 - OK

{
  "operators": [
    {
      "id": 174294,
      "name": "Ionity"
    },
    {
      "id": 213241,
      "name": "The New Motion"
    }
  ],
  "cursor": "H6Zb4Z8p+4/vhPl9JKVHM+9/XWoF02I4EIKblAd3nMk="
}

Error responses:

• 500 - Internal server error.

Aggregation

If the 'aggregate' parameter is set to true, but an aggregation rectangle will contain only one location, then it will end up in the locations array. This means both locations and aggregates arrays can be filled. If there is only one location in the aggregation rectangle, then it will end up in locations array.

If 'aggregate' parameter is absent or false, then aggregates array will not appear in the results at all.

Here is a table describing the sizes of a rectangles, used for each aggregation level:

📘

Aggregation can not be selected if openNow filter is set to true. Doing so returns400.

Filtering

When using filters (i.e. location status filter), then the result will contain each location
that have at least one evse with this status. This means that when you enter AVAILABLE in the filter,
you might get a location with 5 evses, out of which only one will have status AVAILABLE.
Evses with other statuses will have to be filtered out on client side.

Same rule applies to all other filters relating to evse or connector: if even one evse/connector
fulfills the filtering, then the whole location with all evses and connectors will be returned.

Object model:

• connectorStandards (array of strings, optional)
• locationStatuses (array of statuses, optional)
• capabilities (array of charger capabilities, optional) - any value from ones listed in Capabilities
• power (integer, optional) - in Watts; the value you provide represents the connector minimum power value
• powerType (string/enum, optional) - this value can be either AC or DC
• operatorIds (array of integers, optional) - more about Operator ids
• excludedOperatorIds (array of integers, optional) - more about Excluded operator ids
• open247 (boolean, optional) - only chargers open 24/7 are returned
• openNow (boolean, optional) - only chargers open right now (or 24/7) will be returned. Having open247 set to true will render this filter nonfunctional. This filter can not be used together with aggregation, doing so returns 400.
• evseIds (array of strings, optional) - more about EVSE Ids filter
• countries (array of strings, optional) - array of 3-letter country code values to filter locations SWE, NLD and etc.

Operator ids

This array of integer ids represent a filter where only the chargers from the operators provided will be returned.
If this value is provided it will ignore excludedOperatorIds if also provided.

Excluded operator ids

This array of integer ids represent a filter where the chargers belonging to the operators provided will be
excluded from the results. If operatorIds are provided, this array will be ignored.

EVSE Ids

This array of EVSE Ids matches whole parts of EVSE Id. That means, to match an example EVSE Id of IE*ION*E406304
one can use following filters: IE, IE*ION, *ION*, ION. Special characters are not taken into account,
but they split the phrase and each part of the phrase must fully match. Because of this, a string ION*E4 will not
match this EVSE id, because E4 part doesn't match with any full part of the original EVSE Id.

When multiple EVSE Id filters are provided, then the results will be combined.

Options

The filterEvsesAndConnectors option will remove connectors and evses which do not match to filters.
If removing a connector will result in Evse having 0 connectors, then the whole Evse will be removed.

Prices

For performance reasons, prices are only available on the Get location by id endpoint.
In some rare cases, the price might be absent. If the price is not available, it is recommended to display a message to the end user such as "Price temporarily unavailable".

Price object model

• id (string) - Price id
• description (string) - Human-readable price description, e.g. € 0.56/kWh
• currency (string) - Three-letter currency code (ISO 4217 format)
• elements (array, required) - Possible prices for that connector, depending on restrictions
  • price_components (array)
    • price (number) - Cost in the currency stated above. Decimal number. For example, if currency is EUR and price is 1.10, the cost is €1.10. More information on pricing can be found below
    • type (string/enum) - Can be one of TIME, ENERGY, FLAT, PARKING_TIME
    • step_size (number) - The smallest unit of usage that will be billed. Unit: seconds for TIME and PARKING_TIME, watt-hours (Wh) for ENERGY. Check explanation below
  • restrictions (object) - Each restriction can contain one or more of the following properties (it can also be empty):
    • start_time (string) - example: 11:30 - local time when this price element starts applying
    • end_time (string) - example: 21:00 - local time when this price element ends applying
    • day_of_week (array of string/enum) - possible values: [MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY].
    • min_duration (number) - minimum duration (in seconds) to apply this price element
    • max_duration (number)
    • min_kwh (number) - total power (in kWh) charged throughout the session to apply this price element
    • max_kwh (number)

Explanation

The first price element that matches all restrictions is selected. Then, the components from that element are combined to calculate the final price.

Units for price and step_size per type:
| Type | Price Unit | Step Size Unit |
|-----------------|--------------------|----------------------|
| TIME | hour | seconds |
| PARKING_TIME | hour | seconds |
| ENERGY | kWh | Wh |
| FLAT | session | ignored (N/A) |

How step_size works

Example:

{
  "type": "TIME",
  "step_size": 300,
  "price_per_hour": 6.00
}

When type is TIME, step_size is in seconds (see table above). 300 seconds equals 5 minutes, so in this case the customer will be billed in 5-minutes blocks.
If the user charges for 6 minutes, they will be billed for 10 minutes (2 blocks of 300 seconds).
The price is specified for a full hour. In this example, the price is 6.00€. Since 10 minutes is one-sixth of an hour, the user will be charged €1.00 (i.e., €6.00 ÷ 6 = €1.00).

The price elements are defined in the OCPI tariff standard, you can find examples here.

Capabilities

capabilities field is an array of strings.
Unknown values should be accepted in case a new capability is introduced.

Only these capabilities can be taken into account to reliably enable or disable
certain features on a charger:

• REMOTE_START_STOP_CAPABLE: indicates that the charger can be started remotely (see Remote charging)
• PLUG_AND_CHARGE_CAPABLE: indicates that the charger supports Plug & Charge

Location response

📘

Notes about chargers:

• A single charger (EVSE) can have multiple connectors (for example if it supports multiple connector types), but only one vehicle can be charging at a given time.
• The evse_id is the charger identifier physically visible on chargers. It is the one that should be shown to users.

Response fields:

• location (object)
  • id (string) - location id (max. 256 chars)
  • name (string) - location name
  • coordinates
    • latitude (string) - latitude of the point in decimal degree. Example: 50.770774. Decimal separator: "."
    • longitude (string) - longitude of the point in decimal degree. Example: -2.104965. Decimal separator: "."
  • evses (array) - contains all the chargers of a location
    • uid (string) - location's identifier (max. 256 chars). Not meant to be shown to users.
    • evse_id (string, optional) - charger evse id (example "NL*NUO*EEVB*P1406023*1") (max. 128 chars). This is the identifier users can physically see on the charger.
    • status (string/enum) - charger status; explained in Statuses section
    • connectors (array) - contains all connectors a charger has
      • id (string)- connector id (max. 350 chars)
      • standard (string) - charging connector type; explained in Connector standards section
      • power (integer, optional) - maximum power delivered by the connector, in Watts
      • power_type (string/enum) - describes AC/DC and phases. Possible values: [AC, DC, AC_1_PHASE, AC_3_PHASE]
      • price (object, optional) - Only available for Get location by id request. See Prices
      • max_amperage (integer, optional) - max possible amperage
      • max_voltage (integer, optional) - max possible voltage
    • capabilities (string array) - indicates the charger's capabilities. Includes but is not limited to values listed in: Capabilities
    • last_updated (iso datetime string) - timestamp at which the charger information was last updated
  • operator (object)
    • id (string) - operator identifier (can be used to filter on operators)
    • name (string) - operator name
    • external_id (string, optional) - the operator's external id (e.g. "DE*ABC")
    • hotline (string, optional) - hotline phone number (e.g. "+498944255071")
  • openNow (boolean, optional) - indicates if the location is open at the time the request is made. Only present if the open status can be determined by the data provided in the opening_times field (see below).
  • opening_times
    • twentyfourseven (boolean) - if true, indicates that the location is always open
    • regular_hours (array, optional) - ignore if twentyfourseven is true
      • weekday (number) - number of day in the week, from Monday (1) to Sunday (7)
      • period_begin (string) - start time (ex. 08:00), in local time
      • period_end (string) - end time (ex. 16:00), in local time
    • exceptional_openings (array, optional) - lists exceptional days and opening hours (rarely used)
      • period_begin (string) - start time (2022-02-03T08:00.000), in UTC
      • period_end (string) - end time (2022-02-03T16:00.000), in UTC
    • exceptional_closings (array, optional) - lists exceptional days and closing hours (rarely used)
      • period_begin (string) - start time (2022-02-03T08:00.000)
      • period_end (string) - end time (2022-02-03T16:00.000)
  • directions (object, optional)
    • language (string) - example: "en"
    • text (string) - description that helps the user locate the charger
  • country (string) - 3-letter country code
  • state (string, optional) - State, region or province of the Location if available
  • city (string)
  • postal_code (string)
  • address (string)
  • is_green_energy (boolean)
  • last_updated (iso datetime string) - timestamp at which the location information was last updated

Example response:

{
  "id": "RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsY3bpUUSltGvHv9J7jAmBVd",
  "coordinates": {
    "latitude": "51.861337",
    "longitude": "4.548161"
  },
  "operator": {
    "id": "1006200",
    "name": "has.to.be GmbH",
    "external_id": "DE*ABC"
  },
  "opening_times": {
    "twentyfourseven": false,
    "regular_hours": [{
        "period_begin": "08:30",
        "period_end": "18:30",
        "weekday": 1
    }],
    "exceptional_closings": [],
    "exceptional_openings": []
  },
  "directions": [],
  "name": "Licht NL B.V. AC Charger",
  "openNow": true,
  "evses": [
    {
      "uid": "RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsawwqypdT1Qwa3ck8cchZpEGqvvgm+MRKnhx7d45IK35Q==",
      "evse_id": "AT*HTB*E1000145",
      "status": "AVAILABLE",
      "connectors": [
        {
          "id": "RfZBL8BkRQrTa//7TOadw3oiP51NudvmvpRC5WI3TsawwqypdT1Qwa3ck8cchZpEBMfnvAnCytjNeiXwY4yqmQ==",
          "standard": "Type2",
          "power": 22,
          "power_type": "AC",
          "price": {
            "id": "09399a33e80a9145",
            "description": "SEK 1/kWh",
            "currency": "SEK",
            "elements": [
              {
                "restrictions": {
                  "max_duration": 60
                },
                "price_components": [
                  {
                    "price": 0,
                    "type": "TIME",
                    "step_size": 60
                  }
                ]
              },
              {
                "price_components": [
                  {
                    "price": 600,
                    "type": "TIME",
                    "step_size": 60
                  }
                ]
              },
              {
                "restrictions": {
                  "max_duration": 60
                },
                "price_components": [
                  {
                    "price": 1,
                    "type": "FLAT",
                    "step_size": 1
                  }
                ]
              }
            ]
          },
          "max_amperage": 32,
          "max_voltage": 400
        }
      ],
      "capabilities": [
        "REMOTE_START_STOP_CAPABLE",
        "RFID_READER"
      ],
      "last_updated": "2020-09-29T23:08:32Z"
    }
  ],
  "country": "NLD",
  "city": "Barendrecht",
  "postal_code": "2991",
  "address": "Zweth 30 ",
  "is_green_energy": false,
  "last_updated": "2020-09-29T23:08:32.123Z"
}

EVSE statuses

Connector standards

Unrecognized connector standards should be mapped to UNKNOWN type.