Plugsurfing · Schema

Location

CompanyEV ChargingRoamingEurope

Properties

Name Type Description
id string
name string Human-readable name of the charging location
coordinates object Geographic coordinates of the charging location. These values are returned as strings.
evses array List of Electric Vehicle Supply Equipment (EVSE) at this location. Each EVSE may have multiple connectors.
parking_type object Parking type for the charging location.
operator object Information about the Charging Point Operator (CPO) managing this location
operator_display_name string 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 operat
opening_times object Operating hours of the charging location
directions array Navigation instructions to help locate the charging points, available in multiple languages
country string Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated
state string State, region, or province where the charging location is situated. Format varies by country.
city string City where the charging location is situated
postal_code string Postal code of the charging location
address string Street address of the charging location
openNow boolean Indicates if the location is currently open based on opening_hours and local timezone. Use this for quick filtering of available locations.
is_green_energy boolean Indicates if the location uses renewable energy sources for charging, based on CPO-provided data
last_updated string ISO 8601 timestamp of when this location's data was last updated. Use this to track changes and implement efficient polling.
View JSON Schema on GitHub

JSON Schema

plugsurfing-location-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/plugsurfing/main/json-schema/plugsurfing-location-schema.json",
  "title": "Location",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/plugsurfing-reference-openapi.json#/components/schemas/Location",
  "required": [
    "id",
    "name",
    "coordinates",
    "address",
    "evses",
    "country",
    "city",
    "last_updated"
  ],
  "type": "object",
  "properties": {
    "id": {
      "minLength": 0,
      "type": "string"
    },
    "name": {
      "maxLength": 255,
      "minLength": 0,
      "type": "string",
      "description": "Human-readable name of the charging location"
    },
    "coordinates": {
      "$ref": "#/$defs/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": "#/$defs/Evse"
      }
    },
    "parking_type": {
      "description": "Parking type for the charging location.",
      "allOf": [
        {
          "$ref": "#/$defs/ParkingType"
        }
      ]
    },
    "operator": {
      "$ref": "#/$defs/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"
    },
    "opening_times": {
      "$ref": "#/$defs/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": "#/$defs/DisplayText"
      }
    },
    "country": {
      "maxLength": 3,
      "minLength": 3,
      "description": "Three-letter country code (ISO 3166-1 alpha-3) where the charging location is situated",
      "type": "string"
    },
    "state": {
      "description": "State, region, or province where the charging location is situated. Format varies by country.",
      "type": "string"
    },
    "city": {
      "type": "string",
      "description": "City where the charging location is situated"
    },
    "postal_code": {
      "type": "string",
      "description": "Postal code of the charging location"
    },
    "address": {
      "type": "string",
      "description": "Street address of the charging location"
    },
    "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."
    },
    "is_green_energy": {
      "type": "boolean",
      "description": "Indicates if the location uses renewable energy sources for charging, based on CPO-provided data"
    },
    "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."
    }
  },
  "$defs": {
    "BusinessDetails": {
      "required": [
        "id",
        "name"
      ],
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "maxLength": 100,
          "minLength": 0,
          "type": "string"
        },
        "hotline": {
          "type": "string"
        },
        "external_id": {
          "type": "string"
        }
      }
    },
    "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."
        },
        "standard": {
          "$ref": "#/$defs/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."
        },
        "power_type": {
          "type": "string",
          "enum": [
            "AC_1_PHASE",
            "AC_3_PHASE",
            "DC",
            "AC"
          ]
        },
        "price": {
          "description": "Pricing information for this connector. Only available when retrieving a specific location.",
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "description": {
              "type": "string",
              "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)"
            },
            "priceIncludesVat": {
              "type": "boolean",
              "description": "Indicates whether the price includes VAT or not (same meaning as for the CDR object)"
            },
            "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)"
            },
            "elements": {
              "type": "array",
              "description": "Possible prices for that connector, depending on restrictions",
              "items": {
                "$ref": "#/$defs/PriceElement"
              }
            }
          }
        },
        "max_amperage": {
          "description": "Maximum current in Amperes that this connector can provide",
          "type": "number"
        },
        "max_voltage": {
          "description": "Maximum voltage in Volts that this connector can provide",
          "type": "number"
        }
      }
    },
    "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"
      ]
    },
    "ConnectorStatus": {
      "type": "string",
      "enum": [
        "AVAILABLE",
        "CHARGING",
        "BLOCKED",
        "INOPERATIVE",
        "OCCUPIED",
        "OFFLINE",
        "OUTOFORDER",
        "PLANNED",
        "REMOVED",
        "RESERVED",
        "UNKNOWN",
        "UNAVAILABLE"
      ]
    },
    "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`."
        },
        "longitude": {
          "pattern": "-?[0-9]{1,3}\\.[0-9]{6}",
          "type": "string",
          "description": "Longitude serialized as a string, for example `13.350794`."
        }
      }
    },
    "DisplayText": {
      "type": "object",
      "required": [
        "language",
        "text"
      ],
      "properties": {
        "language": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "text": {
          "type": "string",
          "maxLength": 512
        }
      }
    },
    "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"
        },
        "evse_id": {
          "minLength": 1,
          "type": "string"
        },
        "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"
        },
        "status": {
          "$ref": "#/$defs/ConnectorStatus"
        },
        "connectors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/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"
          }
        },
        "parking_restrictions": {
          "type": "array",
          "description": "Parking restrictions for this EVSE.",
          "items": {
            "$ref": "#/$defs/ParkingRestriction"
          }
        },
        "last_updated": {
          "type": "string",
          "format": "date-time",
          "description": "Time the EVSE data was last updated by the operator. Any EVSE data update changes it, so it does not show when the current `status` started. Use `status_since` from Get location live data for charging timing."
        }
      }
    },
    "ExceptionalPeriod": {
      "required": [
        "period_begin",
        "period_end"
      ],
      "properties": {
        "period_begin": {
          "type": "string",
          "format": "date-time"
        },
        "period_end": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "OpeningTimes": {
      "required": [
        "twentyfourseven"
      ],
      "type": "object",
      "properties": {
        "twentyfourseven": {
          "type": "boolean"
        },
        "regular_hours": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RegularHours"
          }
        },
        "exceptional_openings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ExceptionalPeriod"
          }
        },
        "exceptional_closings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ExceptionalPeriod"
          }
        }
      }
    },
    "ParkingRestriction": {
      "type": "string",
      "enum": [
        "EV_ONLY",
        "PLUGGED",
        "DISABLED",
        "CUSTOMERS",
        "MOTORCYCLES"
      ]
    },
    "ParkingType": {
      "type": "string",
      "enum": [
        "ALONG_MOTORWAY",
        "PARKING_GARAGE",
        "PARKING_LOT",
        "ON_DRIVEWAY",
        "ON_STREET",
        "UNDERGROUND_GARAGE"
      ]
    },
    "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",
          "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",
          "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",
          "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"
        }
      }
    },
    "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": "#/$defs/PriceComponent"
          }
        },
        "restrictions": {
          "type": "object",
          "description": "Conditions under which this price element applies. Multiple restrictions can be combined.",
          "properties": {
            "start_time": {
              "type": "string",
              "description": "Time of day when this price starts applying (local time at the charging location)"
            },
            "end_time": {
              "type": "string",
              "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"
            },
            "min_duration": {
              "type": "number",
              "description": "Minimum charging duration in seconds before this price applies (e.g., 7200 means this price applies after 2 hours)"
            },
            "max_duration": {
              "type": "number",
              "description": "Maximum charging duration in seconds for this price to apply"
            },
            "min_kwh": {
              "type": "number",
              "description": "Minimum energy consumption in kWh before this price applies"
            },
            "max_kwh": {
              "type": "number",
              "description": "Maximum energy consumption in kWh for this price to apply"
            },
            "min_vehicle_soc": {
              "type": "number",
              "description": "Minimum vehicle state of charge percentage for which this price element is valid"
            },
            "max_vehicle_soc": {
              "type": "number",
              "description": "Maximum vehicle state of charge percentage for which this price element is valid"
            },
            "min_congestion_threshold": {
              "type": "number",
              "description": "Minimum location utilization percentage for which this price element is valid"
            },
            "max_congestion_threshold": {
              "type": "number",
              "description": "Maximum location utilization percentage for which this price element is valid"
            }
          }
        }
      }
    },
    "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)"
        },
        "period_begin": {
          "type": "string",
          "format": "([0-1][0-9]|2[0-3]):[0-5][0-9]"
        },
        "period_end": {
          "type": "string",
          "format": "([0-1][0-9]|2[0-3]):[0-5][0-9]"
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema 
curl "https://apis.io/api/v1/json-schemas/plugsurfing-location"
All schemas 
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.