Station Get Surface

Request

"station-get-surface" identifies the call as a station-get-surface call.

Define a rectangle on a map by providing two corners:

1. Minimum latitude and longitude

2. Maximum latitude and longitude

Fields

user (optional)

This field identifies the customer (object).

identifier-type

How to identify the user (string).

The identifier-type can be one of:

• "evco-id"

• "rfid"

• "username"

• "token"

identifier

The identifier is something that uniquely identifies the customer, depending on the identifier-type (string).

token (optional)

A token can be used to authenticate the user (string).

For example: if the identifier type is username and the identifier is the user’s username, then token is used for authentication instead of a password.

min-lat

Minimum latitude of the area you are querying (float).

max-lat

Maximum latitude of the area you are querying (float).

min-long

Minimum longitude of the area you are querying (float).

max-long

Maximum longitude of the area you are querying (float).

filters

An object to filter the response (object).

Omit any filter you do not want to use in the request.

Available Filters:

excludes

A list of station IDs to exclude from the result (array of integers).

company-types

A list of owner types of the charging stations (array of strings).

E.g. "hotel".

connector-types

A list of connector types to filter for (array of strings).

Allowed types are:

• "Type2"

• "Combo"

• "Chademo"

• "Schuko"

• "Type3"

• "CeeBlue"

• "3PinSquare"

• "Type1"

• "CeeRed"

• "Cee2Poles"

• "Tesla"

• "Scame"

• "Nema5"

• "CeePlus"

• "T13"

• "T15"

• "T23"

• "Marechal"

• "TypeE"

connector-speeds-greater

Minimum value for charging speed in kW (float).

connector-speeds-less

Maximum value for charging speed in kw (float).

operator-ids

List of charging station operator ids (array of integers).

payable

List of service providers that should be available (array of strings).

Examples are

• "PSA_EU" for PlugSurfing App payable

• "PSC_EU" for PlugSurfing Charging Key payable

Response

Fields

hasMore

Value indicating are there more stations within provided coordinates satisfying provided filters (boolean).

stations

An array of charging stations (objects).

id

The reponder’s ID of the station (integer).

Use this ID in the excludes filter (see request) or to get more details. See also Station Get By IDs.

name

The name of the station, human readable (string).

latitude

Latitude of this station (float).

longitude

Longitude of this station (float).

dynamic-status-summary

Whether the station has available connectors (string).

Can be one of:

• "Available"

• "Occupied"

• "Offline"

• null

owner-type

The type of the company (string or null).

E.g. “hotel”.

last-static-change

The last time the station was updated (string).

The date/time format is RFC3339 (Y-m-d\TH:i:sP).

connector-statuses

Array of connectors’ statuses (id (string): status (string)).

connector-reservations (optional)

Array of connectors’ reservations (id (string): reservation (object)).

reservation

end

When this reservation ends (string; format RFC3339 "2016-05-09T04:08:06+02:00")

own

If reservation by the user included in User request object. If request object isn’t set this will default to false. (boolean)

HTTP Status codes

200 OK

The request was processed successfully.

Result codes

0

Success

Examples

Request:

{
    "station-get-surface": {
        "min-lat": 0,
        "max-lat": 45,
        "min-long": 30,
        "max-long": 40,
        "filters": {
            "excludes": [
                11131
            ],
            "company-types": [
                "hotel"
            ],
            "connector-types": [
                "Type2"
            ],
            "connector-speeds-greater": 3,
            "connector-speeds-less": 100,
            "operator-ids": [
                122,
                32
            ],
            "payable": [
                "app",
                "rfid"
            ]
        }
    }
}

{
    "station-get-surface": {
        "user": {
            "identifier-type": "username",
            "identifier": "john",
            "token": "b3853b6d910849f3b4392555b8acb984"
        },
        "min-lat": 0,
        "max-lat": 45,
        "min-long": 30,
        "max-long": 40,
        "filters": {
            "excludes": [
                11131
            ],
            "company-types": [
                "hotel"
            ],
            "connector-types": [
                "Type2"
            ],
            "connector-speeds-greater": 3,
            "connector-speeds-less": 100,
            "operator-ids": [
                122,
                32
            ],
            "payable": [
                "app",
                "rfid"
            ]
        }
    }
}

Response:

{
    "stations": [
        {
            "id": 1169,
            "name": "Marktparkhaus am Südwall",
            "latitude": 51.516123,
            "longitude": 6.322554,
            "dynamic-status-summary": null,
            "owner-type": null,
            "last-static-change": "2017-01-13T18:07:23+01:00",
            "connector-statuses": {
                "165946": "Available",
                "165947": "Available"
            }
        },
        {
            "id": 1622,
            "name": "Markt",
            "latitude": 51.51599,
            "longitude": 6.322551,
            "dynamic-status-summary": null,
            "owner-type": null,
            "last-static-change": "2017-01-13T18:07:23+01:00",
            "connector-statuses": {
                "142867": "Unknown"
            },
            "connector-reservations": {
                "142867": {
                    "end": "2017-01-14T12:37:11+01:00",
                    "own": false
                }
            }
        }
    ],
    "hasMore": false,
    "result": {
        "code": 0,
        "message": "Success."
    }
}