Geosearch

Overview

The Geosearch API provides multiple ways to find and retrieve charging location information:

• Radius Search: Find chargers within a specified distance from a point
• Route Search: Search for chargers along a travel route
• Batch Retrieval: Get all locations for full data synchronization

For each charging location, you can access:

• Available connectors and specifications
• Real-time availability status
• Opening hours
• Operator details
• Physical location and directions

Radius Search

API Reference

Radius search helps users find charging locations near a specific point. This is useful for:

• Finding chargers near the user's current location
• Discovering charging options in a particular area
• Analyzing charging infrastructure density

Basic Usage

POST /v1/geosearch/radius?latitude=52.3&longitude=4.7

{
  "filters": {
    "locationStatuses": ["AVAILABLE"]
  }
}

This will return up to 300 available charging locations within 3000 meters of the specified point.

Advanced Search Options

1. Adjusting Search Area

• Use the distance parameter to change the search radius (in meters)
• Larger radius will return more results but might lead to a slower response
• For better performance with large radius searches, consider using aggregation

2. Filtering Results

You can narrow down results using various filters:

{
  "filters": {
    "locationStatuses": ["AVAILABLE"], // Only show available chargers
    "powerType": "DC", // Only DC chargers
    "power": 50000, // Min 50kW power
    "open247": true // Only 24/7 locations
  }
}

3. Using Aggregation

For large areas, you can use aggregation to get clustered results:

POST /v1/geosearch/radius?latitude=58.5&longitude=14.75&aggregate=true&aggregationPrecision=5

{
  "filters": {
    "powerType": "DC"
  }
}

This returns clusters of charging locations instead of individual points, making it ideal for:

• Map overview displays
• Understanding charging density in large areas
• Faster response times for large radius searches

Route Search

API Reference

Route search helps find chargers along a route by passing a set of points that this route consists of. This is useful to let the user find convenient charging stops during their trip.

Example request:

{
  "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
  }
}

Location by id

API Reference

This endpoint returns all details for a given location, and unlike the other geosearch endpoints, it includes prices.

📘

The locationId is part of the URL, please make sure to URL-encode id

Prices

When retrieving location details, it is possible to specify the user, charging key of fleet for which prices should be looked-up (if no parameter is provided, default prices are returned).

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. VAT is included. 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:

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.

Locations batch

API Reference

This endpoint allows you to retrieve all available locations one page at a time.
Locations are returned sorted by their last update timestamp (last_updated field) in ascending order, meaning the most recently updated location appears last in the result.

The most efficient way to use this endpoint is to:

1. Perform a FULL PULL:
   1. Issue a request to /v1/locations/batch to retrieve the first page of locations along with a cursor.
   2. Continue requesting more locations using /v1/locations/batch?cursor=<cursor_from_previous_request>, where cursor_from_previous_request is the cursor returned by the previous request.
   3. Repeat until the response does not include a new cursor, indicating there are no more locations to retrieve.
2. After the FULL PULL (1), perform regular 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.

A FULL PULL is required when setting up the integration and should also be performed regularly to ensure complete synchronization. While DELTA PULLs capture updates efficiently, periodic FULL PULLs allow you to detect locations that no longer exist and mark them as hidden. One approach is to hide locations that have a last_updated timestamp older than the latest FULL PULL.

If a failure occurs during a PULL process, you can use the cursor to resume. For instance, if the process crashes after 500 pages, you can restart from the last successfully processed page by using the last returned cursor.

Operators List

API Reference

The API provides access to a list of Charging Point Operators (CPOs) whose chargers are available through the geosearch endpoints. This is useful for:

• Displaying operator names in your UI
• Filtering geosearch results by specific operators

The first page should be fetched without providing any cursor. Use the cursor provided in the response of each page to get the next page. The last page has no cursor.

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

Important considerations when filtering:

• A location is included if ANY of its connectors match the filter criteria
• Results include ALL connectors at matching locations
• Client-side filtering may be needed for specific connectors
• Multiple filters can be combined
• Operator filtering takes precedence over exclusions

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

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

Filtering on 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.

Filtering EVSE IDs

You can filter locations by their EVSE IDs using partial matching. The filter works by breaking down the EVSE ID into parts and matching those parts:

For example, given an EVSE ID IE*ION*E406304:

✅ These filters will match:

• IE (matches first part)
• ION (matches middle part)
• IE*ION (matches beginning)
• *ION* (matches middle)

❌ These filters won't match:

• ION*E4 (because E4 is only part of E406304)
• 406 (because it's only part of a segment)

Key points:

• Special characters like * act as separators
• Each filter must match a complete segment
• When using multiple EVSE ID filters, a match on any filter will include the location

This filtering is useful when you want to find chargers from specific networks or locations that follow known ID patterns.

Connector Standards

The API supports a wide range of connector types:

• Standard AC connectors (Type 1, Type 2, etc.)
• DC fast charging (CCS, CHAdeMO)
• Tesla connectors
• Industrial and domestic sockets

Unrecognized connector standards should be mapped to UNKNOWN type.

EVSE Statuses

Understand these charger status values for proper handling and UI display:

• AVAILABLE - Ready for charging
• CHARGING - Currently in use
• OCCUPIED - Same as CHARGING
• RESERVED - Should be treated in the same way as CHARGING
• BLOCKED - Physically inaccessible
• INOPERATIVE - Temporarily unavailable
• OUTOFORDER - Broken or under maintenance
• PLANNED - Not yet installed (should be hidden)
• REMOVED - No longer exists (should be hidden)
• OFFLINE - Charger did not send any updates for unknown reason
• UNKNOWN - Status is not known (shouldn't be marked as Available)

Capabilities

The 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