> ## Documentation Index > Fetch the complete documentation index at: https://developer.plugsurfing.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch locations > Retrieve locations in batches. Locations are returned sorted by last_updated timestamp in ascending order. Prices are not included, to get prices for a given location, use Get location by id. Best practices ## OpenAPI ````yaml reference/openapi.json GET /drive/v1/locations/batch openapi: 3.1.0 info: title: Drive API version: 1.0.0 description: >- The Drive API provides comprehensive access to Plugsurfing's charging infrastructure network. It enables you to manage users, charging keys, search for charging locations, handle payments, and control charging sessions. servers: - url: https://{environment}.plugsurfing.com variables: environment: enum: - drive-api-stage default: drive-api-stage description: >- API environment - use drive-api-stage for testing and drive-api for production security: [] tags: - name: Geosearch description: >- Search and retrieve detailed information about charging locations and stations - name: Users description: >- Manage user accounts including creation, retrieval, updates, and deletion. Handles user-specific data and preferences. - name: Charging Keys description: >- Manage physical and virtual charging keys including creation, activation, updates, and status management. Essential for user access to charging stations. - name: Sessions description: >- Access and manage charging session data including history, status, and detailed session information - name: Remote Charging description: >- Control charging sessions remotely including starting and stopping sessions, and monitoring session status - name: Payment Options description: >- Manage payment methods and handle transaction processing for charging services - name: User Groups description: Manage user group memberships - name: Vouchers description: Redeem vouchers - name: Charging Key Orders description: Handle the ordering and fulfillment process for physical charging keys - name: EMP Charging Keys description: E-Mobility Provider specific endpoints for managing charging keys - name: EMP Geosearch description: E-Mobility Provider specific endpoints for location search and information - name: EMP Orders description: E-Mobility Provider specific endpoints for managing orders - name: EMP Sessions description: E-Mobility Provider specific endpoints for managing charging sessions - name: EMP Fleets description: E-Mobility Provider specific endpoints for managing fleets paths: /drive/v1/locations/batch: get: tags: - Geosearch summary: Batch locations description: >- Retrieve locations in batches. Locations are returned sorted by last_updated timestamp in ascending order. Prices are not included, to get prices for a given location, use Get location by id. Best practices: 1. Perform initial FULL PULL by paginating through all locations 2. Perform regular DELTA PULLS using last_updated parameter to get only updated locations 3. Use the last_updated value of the last location in the last page as the starting point for next DELTA PULL 4. Perform periodic FULL PULLS to detect removed locations 5. Use cursor to resume interrupted pulls operationId: getLocationsBatch parameters: - name: page_size in: query description: Optional - used to set page size value required: false schema: type: number minimum: 10 maximum: 500 default: 50 - name: cursor in: query description: Optional - pass cursor from previous response body to get next page. required: false schema: type: string - name: last_updated in: query description: >- Optional - when set, only locations updated after this date are returned. example `2024-05-27T10:44:48Z`. required: false schema: type: string - name: countries in: query description: >- Optional - when set, only locations in these countries are returned. example `DEU` or `DEU,FRA`. required: false schema: type: string - name: power_type in: query description: >- Optional - when set, only locations having at least one connector with this power_type are returned. possible values: `AC` or `DC`. required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BatchLocationsResponse' example: locations: - id: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo= name: Ebee Smart Technologies coordinates: latitude: '52.475911' longitude: '13.350794' evses: - uid: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE evse_id: +49*839*030*000074 physical_reference: '4' status: AVAILABLE connectors: - {} capabilities: - RESERVABLE - PLUG_AND_CHARGE_CAPABLE - PLUG_AND_CHARGE_CAPABLE last_updated: '2025-01-15T10:30:00Z' operator: id: '881941' name: Ebee Smart Technologies hotline: '+498944255071' external_id: DE*ABC operator_display_name: Sub-operator X opening_times: twentyfourseven: false regular_hours: - weekday: 1 period_begin: '00:10' period_end: '29:59' exceptional_openings: - period_begin: '2025-01-15T10:30:00Z' period_end: '2025-01-15T10:30:00Z' exceptional_closings: - period_begin: '2025-01-15T10:30:00Z' period_end: '2025-01-15T10:30:00Z' directions: - language: DE text: example country: DEU state: Bayern city: Berlin postal_code: 10829 address: EUREF CAMPUS 4-5 openNow: false is_green_energy: false last_updated: '2024-03-15T14:30:00Z' cursor: string '400': description: The provided query parameters, route parameters or body is invalid. content: application/json: schema: $ref: '#/components/schemas/InvalidRequestErrorResponse' example: message: Invalid request payload details: - field X is required '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: message: Resource not found security: - ApiKeyAuth: [] components: schemas: BatchLocationsResponse: type: object required: - locations properties: locations: type: array items: $ref: '#/components/schemas/Location' description: Locations returned in the current page. cursor: type: string description: >- The cursor pointing to the next page, when missing it means there are no more pages to fetch. description: Paginated response containing a batch of charging locations. InvalidRequestErrorResponse: title: InvalidRequestErrorResponse type: object required: - message - fields properties: message: type: string fields: type: array items: title: InvalidField type: object required: - name - message - rejectedValue properties: name: type: string message: type: string example: UserId is not correct rejectedValue: type: string ErrorResponse: title: ErrorResponse type: object properties: message: type: string Location: required: - id - name - coordinates - address - evses - country - city - last_updated type: object properties: id: minLength: 0 type: string example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0gQhJv/Yjp5FXBJt14SccU9zFRdnC4SV7juPdCRaWkEZo= name: maxLength: 255 minLength: 0 type: string description: Human-readable name of the charging location example: Ebee Smart Technologies coordinates: $ref: '#/components/schemas/Coordinates' description: >- Geographic coordinates of the charging location. These values are returned as strings. evses: type: array description: >- List of Electric Vehicle Supply Equipment (EVSE) at this location. Each EVSE may have multiple connectors. items: $ref: '#/components/schemas/Evse' parking_type: description: Parking type for the charging location. allOf: - $ref: '#/components/schemas/ParkingType' operator: $ref: '#/components/schemas/BusinessDetails' description: >- Information about the Charging Point Operator (CPO) managing this location operator_display_name: description: >- An enhanced display name of the operator. This may be the operator name as found in the operator object, or the sub-operator of the location. When showing the location to end users, this is the operator name that should be shown. type: string example: Sub-operator X opening_times: $ref: '#/components/schemas/OpeningTimes' description: Operating hours of the charging location directions: type: array description: >- Navigation instructions to help locate the charging points, available in multiple languages items: $ref: '#/components/schemas/DisplayText' country: maxLength: 3 minLength: 3 description: >- Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated type: string example: DEU state: description: >- State, region, or province where the charging location is situated. Format varies by country. type: string example: Bayern city: type: string description: City where the charging location is situated example: Berlin postal_code: type: string description: Postal code of the charging location example: 10829 address: type: string description: Street address of the charging location example: EUREF CAMPUS 4-5 openNow: type: boolean description: >- Indicates if the location is currently open based on opening_hours and local timezone. Use this for quick filtering of available locations. example: false is_green_energy: type: boolean description: >- Indicates if the location uses renewable energy sources for charging, based on CPO-provided data example: false last_updated: type: string description: >- ISO 8601 timestamp of when this location's data was last updated. Use this to track changes and implement efficient polling. example: '2024-03-15T14:30:00Z' Coordinates: type: object description: >- Latitude and longitude values serialized as strings with fixed decimal precision. This schema is used in response payloads and in route-search points. properties: latitude: pattern: '-?[0-9]{1,2}\.[0-9]{6}' type: string description: Latitude serialized as a string, for example `52.475911`. example: '52.475911' longitude: pattern: '-?[0-9]{1,3}\.[0-9]{6}' type: string description: Longitude serialized as a string, for example `13.350794`. example: '13.350794' Evse: required: - uid - status - connectors - capabilities - last_updated type: object description: >- Electric Vehicle Supply Equipment (EVSE) represents a charging station unit that may have multiple connectors. Only one connector can be active at a time. properties: uid: minLength: 0 type: string example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJG9qMC0Dp9OqeegGRXmiTOE evse_id: minLength: 1 type: string example: +49*839*030*000074 physical_reference: type: string description: >- The 'physical reference' is used by some CPOs to represent the label printed on the charging station itself. For example, in a charging location, the physical references could be '1', '2', '3', '4', for the four different charging stations example: '4' status: $ref: '#/components/schemas/ConnectorStatus' connectors: type: array items: $ref: '#/components/schemas/Connector' capabilities: type: array description: >- Values: `PLUG_AND_CHARGE_CAPABLE`, `REMOTE_START_STOP_CAPABLE`. New values in this array might be added without notice, so unknown values should be handled gracefully. items: type: string example: - RESERVABLE - PLUG_AND_CHARGE_CAPABLE - PLUG_AND_CHARGE_CAPABLE parking_restrictions: type: array description: Parking restrictions for this EVSE. items: $ref: '#/components/schemas/ParkingRestriction' example: - EV_ONLY - CUSTOMERS last_updated: type: string format: date-time ParkingType: type: string enum: - ALONG_MOTORWAY - PARKING_GARAGE - PARKING_LOT - ON_DRIVEWAY - ON_STREET - UNDERGROUND_GARAGE example: PARKING_LOT BusinessDetails: required: - id - name type: object properties: id: type: string example: '881941' name: maxLength: 100 minLength: 0 type: string example: Ebee Smart Technologies hotline: type: string example: '+498944255071' external_id: type: string example: DE*ABC OpeningTimes: required: - twentyfourseven type: object properties: twentyfourseven: type: boolean example: false regular_hours: type: array items: $ref: '#/components/schemas/RegularHours' exceptional_openings: type: array items: $ref: '#/components/schemas/ExceptionalPeriod' exceptional_closings: type: array items: $ref: '#/components/schemas/ExceptionalPeriod' DisplayText: type: object required: - language - text properties: language: type: string maxLength: 2 minLength: 2 example: DE text: type: string maxLength: 512 example: example ConnectorStatus: type: string enum: - AVAILABLE - CHARGING - BLOCKED - INOPERATIVE - OCCUPIED - OFFLINE - OUTOFORDER - PLANNED - REMOVED - RESERVED - UNKNOWN - UNAVAILABLE example: AVAILABLE Connector: required: - id - standard - power_type type: object properties: id: minLength: 0 type: string description: >- Unique identifier for this connector. Use this ID when starting charging sessions. example: >- 8rMCionje8s2LtheVGEK90mYnJdJe5OZd48ecF/w1StRJSodFFzfQ3GhJbYbxG0g3wFt7gLfnV3ulxmnoAzR4W/DFEMs63CndZpPK6L2aJEM0D69tJVN05/1hZ1zxqZSJ9kBdNsmfryS0+gvjLNZvdF1pDHJuCTydsJX6vPZh7U= standard: $ref: '#/components/schemas/ConnectorStandard' description: >- Physical connector type/standard (e.g., Type2, Combo, CHADEMO). Use `Combo` for CCS connectors. power: type: integer description: >- Maximum power output in Watts. For AC chargers, this is typically between 3.7kW and 43kW. For DC chargers, typically between 50kW and 350kW. example: 22000 power_type: type: string enum: - AC_1_PHASE - AC_3_PHASE - DC - AC example: AC_3_PHASE price: description: >- Pricing information for this connector. Only available when retrieving a specific location. type: object properties: id: type: string example: 4370769f30bd7927 description: type: string example: € 0.56/kWh, € 0.10/min (> 2 h) description: Human-readable description of the pricing structure currency: type: string description: >- Three-letter currency code ([ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format) example: EUR priceIncludesVat: type: boolean description: >- Indicates whether the price includes VAT or not (same meaning as for the CDR object) example: 'true' vatRate: type: string description: >- The VAT rate that is applied to the price (in case priceIncludesVat=true) or the VAT rate that should be applied to the price (in case priceIncludesVat=false) example: '22' elements: type: array description: Possible prices for that connector, depending on restrictions items: $ref: '#/components/schemas/PriceElement' max_amperage: description: Maximum current in Amperes that this connector can provide type: number example: 32 max_voltage: description: Maximum voltage in Volts that this connector can provide type: number example: 400 ParkingRestriction: type: string enum: - EV_ONLY - PLUGGED - DISABLED - CUSTOMERS - MOTORCYCLES example: EV_ONLY RegularHours: description: Only to be used if twentyfourseven = false required: - weekday - period_begin - period_end properties: weekday: type: integer description: Number of day in the week, from Monday (1) till Sunday (7) example: 1 period_begin: type: string format: ([0-1][0-9]|2[0-3]):[0-5][0-9] example: '00:10' period_end: type: string format: ([0-1][0-9]|2[0-3]):[0-5][0-9] example: '29:59' ExceptionalPeriod: required: - period_begin - period_end properties: period_begin: type: string format: date-time period_end: type: string format: date-time ConnectorStandard: type: string description: >- Connector standard accepted by the API. Use `Combo` for CCS connectors. `CHADEMO` is the preferred token; `Chademo` is a legacy alias. enum: - 3PinSquare - Cee2Poles - CeeBlue - CeePlus - CeeRed - Combo - Marechal - Nema5 - Scame - CHADEMO - Chademo - Type1 - Type2 - Type3 - TypeE - Schuko - UNKNOWN - T23 - T13 - T15 - Tesla - DOMESTIC_A - DOMESTIC_B - DOMESTIC_C - DOMESTIC_D - DOMESTIC_E - DOMESTIC_F - DOMESTIC_G - DOMESTIC_H - DOMESTIC_I - DOMESTIC_J - DOMESTIC_K - DOMESTIC_L - IEC_60309_2_single_16 - IEC_60309_2_three_16 - IEC_60309_2_three_32 - IEC_60309_2_three_64 - IEC_62196_T1 - IEC_62196_T1_COMBO - IEC_62196_T2 - IEC_62196_T2_COMBO - IEC_62196_T3A - IEC_62196_T3C - TESLA_R - TESLA_S example: Type2 PriceElement: type: object required: - price_components description: >- Defines a complete pricing structure that may apply under certain conditions. Multiple price elements may exist for different times or usage patterns. properties: price_components: type: array description: >- List of individual price components that make up this pricing structure items: $ref: '#/components/schemas/PriceComponent' restrictions: type: object description: >- Conditions under which this price element applies. Multiple restrictions can be combined. properties: start_time: type: string example: '08:30' description: >- Time of day when this price starts applying (local time at the charging location) end_time: type: string example: '22:30' description: >- Time of day when this price stops applying (local time at the charging location) day_of_week: type: string enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY description: Days of the week when this price applies example: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY min_duration: type: number example: 7200 description: >- Minimum charging duration in seconds before this price applies (e.g., 7200 means this price applies after 2 hours) max_duration: type: number example: 10000 description: Maximum charging duration in seconds for this price to apply min_kwh: type: number example: 2 description: Minimum energy consumption in kWh before this price applies max_kwh: type: number example: 5 description: Maximum energy consumption in kWh for this price to apply min_vehicle_soc: type: number example: 80 description: >- Minimum vehicle state of charge percentage for which this price element is valid max_vehicle_soc: type: number example: 95 description: >- Maximum vehicle state of charge percentage for which this price element is valid min_congestion_threshold: type: number example: 70 description: >- Minimum location utilization percentage for which this price element is valid max_congestion_threshold: type: number example: 90 description: >- Maximum location utilization percentage for which this price element is valid PriceComponent: type: object description: >- Defines a single component of a charging price. A price can have multiple components (e.g., energy cost + time cost). properties: price: type: number example: 0 description: >- 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 can be found in https://developer.plugsurfing.com/docs/geosearch#explanation type: type: string example: FLAT description: >- More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation enum: - TIME - ENERGY - FLAT - CAPPED - PARKING_TIME - CONGESTION_TIME step_size: type: number example: 1 description: >- The smallest unit of usage that will be billed. Unit: seconds for `TIME`, `PARKING_TIME`, and `CONGESTION_TIME`; watt-hours (Wh) for `ENERGY`; ignored for `FLAT` and `CAPPED`. More information can be found in https://developer.plugsurfing.com/docs/geosearch#explanation securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.