Developer Resources

Get Goodspeed API to gain day-to-day visibility into your company data usage and connectivity costs

Overview

The Goodspeed API provides means for customers with Business Plan to programmatically access information about Goodspeed hotspots and their data usage. Please don't abuse or otherwise use API excessively - if you're unsure about your usage patterns, please confirm it from via email from .

How to use Goodspeed API

Overview

The Goodspeed API follows REST-style pattern for accessing information from Goodspeed service using HTTP-protocol over SSL-tunnel from API-endpoint hosted at URL .

When accessing data via any of the documented API endpoints, request is authenticated with customer's email address as username and system generated API-token as password. Credentials are passed to the API endpoint via following HTTP-headers included in each authenticated API request.

  • X-Goodspeed-Username - Email address for the customer's account (e.g. john@some.net)
  • X-Goodspeed-API-Token - Generated API token for customer (e.g. 1293i123123sedr)

Take note of your API token; it's unique to your account and should be kept private.

Changing this API

The API may be changed without prior notice. Potential changes are following:

  • adding new endpoints
  • adding new parameters to an existing GET method
  • adding new optionally supported parameters to an existing POST/PUT method

In the above cases, the API's will remain backward compatible. Provided API endpoint is versioned and new versions of the API may be introduced for backwards incompatible changes.

API Token

Common responses

200 Ok

The operation invoked by the client application completed successfully.

201 Created

A POST or PUT operation was succesful. Data was added or modified, and there is no data to return.

202 Accepted

Client application invoked an asynchronous request. The results will be available later in the url identified by the location header.

400 Bad Request

Returned when client application sent the request with incorrect syntax (e.g. mandatory parameter is missing or some of the parameter values do not conform to the format introduced in this specification).

401 Unauthorized

Returned when client application is requesting a resource without valid authorization. Application should retry the operation with valid API credentials.

403 Forbidden

Returned when account is locked or expired or otherwise valid credentails don't permit access to target resource.

404 Not Found

Client application attempted to access a non-existent resource or resource is not accessible with the provided credentials

429 Too Many Requests

Server refuses to fulfil the request due the client application sending too many request for a given time period. Application should retry the operation after the number of allowed requests falls back to allowed bounds. Client application must follow a rate limit of 5 requests per 30s time period.

500 Internal Server Error

Server isn't able to fulfil the request due the unexpected (error) condition.

503 Service Unavailable

Server is currently unable to handle request due the temporary overloading or maintenance of the server. This condition implies temporary condition which will be rectified after some delay. If response has 'Retry-After' header, the client should wait specified amount before retrying operation. If no Retry-After is given, response should be treated in same way as response 500 is handled.

API endpoints

List of API endpoints
GET https://goodspeed.io/partner/api/v1/devices
GET https://goodspeed.io/partner/api/v1/devices/%device-serial%
PUT https://goodspeed.io/partner/api/v1/devices/%device-serial%
GET https://goodspeed.io/partner/api/v1/devices/%device-serial%/consumption
GET https://goodspeed.io/partner/api/v1/devices/all/consumption
GET https://goodspeed.io/partner/api/v1/sims/summary
GET https://goodspeed.io/partner/api/v1/sims/%iccid%
GET https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%
GET https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%/quota
PUT https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%/quota
GET https://goodspeed.io/partner/api/v1/events

List devices associated to account

Lists all the devices currently associated with the account. For each device the serial number, label (if available), activation date and current software version are returned.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/devices

Sample response

[
    {
        "sn": "DM622663135",
        "sw": "SW.2.3.16.201312222300",
        "activationDate": "2012-12-12T15:38:11+00:00"
    },
    {
        "sn": "DM123412341",
        "label": "John",
        "sw": "SW.2.3.16.201312222300",
        "activationDate": "2012-12-20T07:15:00+00:00"
    }
]

Field details

  • sn - serial number of associated device
  • label - optional label of device
  • sw - last reported software version of associated device
  • activationDate - activation time of device in ISO8601 -format

Example for cUrl -command line tool

curl -Gs 'https://goodspeed.io/partner/api/v1/devices' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Get configuration of a device

Read configuration of the device (identified by the device serial number in the request url). In addition of the basic data of the device the response lists the ICCID of the simcard, the ISO 3166-1 alpha-2 country code, the type, the status and the UTC offset of the destination currently associated with the device.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/devices/%device-serial%

Sample response

{
    "sn": "DM622663135",
    "label": "XXX1000AA",
    "sw": "SW.2.3.16.201312222300",
    "activationDate": "2012-12-12T12:34:56+00:00",
    "destinations": [
        {
            "iccid": "8935806111212584189",
            "country": "FI",
            "timezone": "+02:00",
            "type": "PREPAID",
            "status": "ACTIVE"
        },
        {
            "iccid": "8934123412341234123",
            "country": "SE",
            "timezone": "+01:00",
            "type": "PERSONAL",
            "status": "ACTIVE"
        },
        {
            "iccid": "8935123412341234123",
            "country": "DK",
            "timezone": "+01:00",
            "type": "PERSONAL",
            "status": "ACTIVE",
            "quota": {
                "enabled": true,
                "fairUseLimit": "980MB",
                "hardLimit": "1GB"
            }
        }
    ]
}

Field details

  • sn - serial number of associated device
  • label - optional label of device
  • sw - last reported software version of associated device
  • activationDate - activation time of device in ISO8601 -format
  • maxRefillCount - Maximum of how many times a daypass refill is charged when data consumption reaches the daily limit, before data is blocked.
  • destinations - list of destinations/countries of device
    • iccid - ICCID of SIM assigned for associated country
    • country - ISO 3166-1 alpha-2 country-code of associated country
    • timezone - Timezone offset for destination country.
    • type - Type of SIM, "PERSONAL" for user owned personal SIMs attached to device, "PREPAID" for destination SIMs provided by Goodspeed
    • status - Optional enumeration for the status of destination country ('ACTIVE', 'INACTIVE', 'BLOCKED').
    • quota - Optional object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Object is not included in response if no limits have been defined for the destination country.
      • enabled - Boolean value indicating whether configured daily data transfer limit is enabled or disabled.
      • fairUseLimit - Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
      • hardLimit - Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Example for cUrl -command line tool

curl -Gs 'https://goodspeed.io/partner/api/v1/devices/DM622663135' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Modify configuration of a device

Modifies device configuration (identified by the device serial number in the request url) - for instance control the device behavior when the data consumption limit has been reached. The parameters are optional, so it is possible to only touch one parameter and leave the rest as they were. Note that only part of the parameters returned of the corresponding GET method can be written by this call, most of them are read-only.

The API returns 404 if the device can not be found by serial number, 400 if the data can not be accepted, and 201 on success.

Request method

PUT

Request URL

https://goodspeed.io/partner/api/v1/devices/%device-serial%

Sample request:

{
    "label": "George",
    "maxRefillCount": 2
}

Field details

  • label - Optional, device label, for easier device identification
  • maxRefillCount - Optional, maximum of how many times a daypass refill is charged when data consumption reaches the daily limit, before data is blocked. Number zero means refills are disabled and only one daypass per day is allowed.

Example:

Disable refills for device DM622663135

curl -X PUT 'https://goodspeed.io/partner/api/v1/devices/DM622663135 \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "maxRefillCount": 0 }' \
    ---compressed

Get summary of SIM-cards

Query overview of all SIM-cards grouped by type and size. If account or any of its device don't have SIM-cards, a response of 204 No Content is returned.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/sims/summary

Parameters

  • type - Optional type of SIM, "PERSONAL" for user owned personal SIMs, "PREPAID" for destination SIMs provided by Goodspeed
  • size - Optional enumeration for the size of the SIM ('MINI', 'MICRO').
  • destinations - Optinal comma separated list of ISO 3166-1 alpha-2 country codes that must be supported by the SIM-card

Sample response

[
    {
        "type": "PERSONAL",
        "size": "MICRO",
        "amount": {
            "inuse": 56,
            "available": 123
        }
    },
    {
        "type": "PREPAID",
        "size": "MICRO",
        "amount": {
            "inuse": 32,
            "available": 1
        }
    },
    {
        "type": "PREPAID",
        "size": "MINI",
        "amount": {
            "inuse": 5
        }
    }
]

Field details

  • type - Type of SIM ('PERSONAL', 'PREPAID', 'POSTPAID')
  • size - Size of SIM ('MINI', 'MICRO', 'UNKNOWN'). The enumeration value of 'UNKNOWN' is used if size of the SIM-card can't be determined in a reliable way.
  • amount - Object containing SIMs currently available and used by devices
    • inuse - Optional number of SIMs assocaited with Goodspeed devices.
    • available - Optional number of SIMs that aren't associated with any devices.

Example: Summary of all SIM-cards for user's account

curl -Gs 'https://goodspeed.io/partner/api/v1/sims/summary' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Example: Summary of all 'PERSONAL'-type SIM-cards supporting Finland and Sweden as destinations

curl -Gs 'https://goodspeed.io/partner/api/v1/sims/summary?type=PERSONAL&destinations=FI,SE' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Query details for a single SIM-card

Query details for a single SIM-card identified by ICCID. If SIM-card isn't found or isn't associated with the user's account, a 404 Not Found is returned.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/sims/%iccid%

Sample response

{
    "size": "MINI"
    "status": "INUSE"
    "destinations": [
        {
            "iccid": "8934123412341234123",
            "country": "SE",
            "timezone": "+01:00",
            "operator": "Hi3G Access AB",
            "type": "PERSONAL",
            "status": "ACTIVE"
        },
        {
            "iccid": "8934123412341234123",
            "country": "DK",
            "timezone": "+01:00",
            "operator": "Hi3G Access AB",
            "type": "PERSONAL",
            "status": "ACTIVE",
            "quota": {
                "enabled": true,
                "fairUseLimit": "980MB",
                "hardLimit": "1GB"
            }
        }
    ]
}

Field details

  • size - Size of the SIM-card ('MINI', 'MICRO', 'UNKNOWN')
  • status - Availability status of the SIM-card ('INUSE', 'AVAILABLE')
  • destinations - list of destinations/countries of SIM-card
    • iccid - ICCID of SIM assigned for associated country
    • type - Type of SIM, "PERSONAL" for user owned personal SIMs attached to device, "PREPAID" for destination SIMs provided by Goodspeed
    • status - Optional enumeration for the status of destination country ('ACTIVE', 'INACTIVE', 'BLOCKED')
    • country - ISO 3166-1 alpha-2 country-code of associated country
    • timezone - Timezone offset for destination country
    • operator - Optional name of the operator for the SIM-card
    • quota - Optional object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Object is not included in response if no limits have been defined for the destination country.
      • enabled - Boolean value indicating whether configured daily data transfer limit is enabled or disabled
      • fairUseLimit - Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
      • hardLimit - Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Example: Query details for a SIM-card with ICCID '8934123412341234123'

curl -Gs 'https://goodspeed.io/partner/api/v1/sims/8934123412341234123 \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Query details for a single destination from a SIM-card

Query details for a single destination country identified from a single SIM-card identified by ISO 3166-1 alpha-2 country code and ICCID. If SIM-card isn't found or specified country isn't available, a 404 Not Found is returned.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%

Sample response

{
    "iccid": "8934123412341234123",
    "country": "SE",
    "timezone": "+01:00",
    "operator": "Hi3G Access AB",
    "type": "PERSONAL",
    "status": "ACTIVE",
    "quota": {
        "enabled": true,
        "fairUseLimit": "980MB",
        "hardLimit": "1GB"
    }
}

Field details

  • iccid - ICCID of SIM assigned for associated country
  • country - ISO 3166-1 alpha-2 country-code of associated country
  • timezone - Timezone offset for destination country
  • operator - Optional name of the operator for the SIM-card
  • type - Type of SIM, "PERSONAL" for user owned personal SIMs attached to device, "PREPAID" for destination SIMs provided by Goodspeed.
  • status - Optional enumeration for the status of destination country ('ACTIVE', 'INACTIVE', 'BLOCKED').
  • quota - Optional object indicating allowed usage limits for daily data transfer for this destination country (KB, MB or GB). Object is not included in response if no limits have been defined for the destination country.
    • enabled - Boolean value indicating whether configured daily data transfer limit is enabled or disabled.
    • fairUseLimit - Fair-use limit for daily data transfer of destination country (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
    • hardLimit - Hard-use limit for daily data transfer of destination country (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Example: Query destination details for 'Sweden' from SIM-card with ICCID of '8934123412341234123'

curl -Gs 'https://goodspeed.io/partner/api/v1/sims/8934123412341234123/country/SE \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Get usage limits for a single destination country

Query usage limit details for a single destination country on a single SIM-card. If no usage limits have configured for the destination country, a response of 204 No Content is returned.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%/quota

Sample response

{
    "enabled": true,
    "fairUseLimit": "980MB",
    "hardLimit": "1GB"
}

Field details

  • enabled - Boolean value indicating whether enforcing of usage limits is enabled or disabled.
  • fairUseLimit - Optional fair-use limit for daily data transfer of destination country on a single SIM-card identified by ICCID (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached. If field isn't present in response, no fair-use limit has been defined for destination country and usage without throttling is allowed for destination country
  • hardLimit - Optional hard-use limit for daily data transfer of destination country on a single SIM-card identified by ICCID (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached. If field isn't present in response, no hard-use limit has been defined for destination country and unlimited usage is allowed.

Example: Query usage limits for destinaton country Denmark on SIM card 8935123412341234123

curl -Gs 'https://goodspeed.io/partner/api/v1/sims/8935123412341234123/country/DK/quota' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Enable, disable or change usage limits for a destination country

Enable, disable or change usage limits for a single destination country on a single SIM card. If a request is received to enable or disable usage limits for a destination country without configured limits, a response of 400 Bad Request is returned. If request a made to enable or disable limits for a destination country with authorization that doesn't allow its modification, a response of 403 Forbidden is returned.

Request method

PUT

Request URL

https://goodspeed.io/partner/api/v1/sims/%iccid%/country/%countrycode%/quota

Sample request:

{
    "enabled": true,
    "fairUseLimit": "980MB",
    "hardLimit": "1GB"
}

Field details

  • enabled - Boolean value indicating wish to enable or disable usage limits.
  • fairUseLimit - Optional fair-use limit for daily data transfer of destination country on a single SIM-card identified by ICCID (KB, MB or GB). Device will throttle data transfer speed for this destination country until end of the current day after the limit has been reached.
  • hardLimit - Optional hard-use limit for daily data transfer of destination country on a single SIM-card identified by ICCID (KB, MB or GB). Device will prevent data transfer for this destination country until end of the current day after the limit has been reached.

Example 1: Set fair-use limit to 1GB and disable hard-use limit for destinaton country Denmark on SIM card 8935123412341234123

curl -X PUT 'https://goodspeed.io/partner/api/v1/sims/8935123412341234123/country/DK/quota \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "enabled": true, "fairUseLimit": "1GB" }' \
    ---compressed

Example 2: Disable usage limits for destinaton country Denmark on SIM card 8935123412341234123

curl -X PUT 'https://goodspeed.io/partner/api/v1/sims/8935123412341234123/country/DK/quota \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    -H 'Content-Type: application/json' \
    -d '{ "enabled": false }' \
    ---compressed

Get data consumption of a device

Hourly data consumption for a single device for given date per active destination. Consumption is returned in user-defined timezone if the client request contains a timezone parameter. Destinations which do not have any recorded data consumption for the given day are not included in the response.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/devices/%device-serial%/consumption?date=2012-12-12T%2B03:00&timezone=%2B00:00

Parameters

  • date - Requested date in date+offset (‘yyyy-MM-dd’T’ZZ’) -format. For example 21th of December 2012 in Finnish winter time would be “2012-12-21T+03:00”. See ISO8601 specification for details. Note that ‘+’ sign needs to be encoded to ‘%2B’, see Percent-encoding )
  • timezone - Optional user-defined timezone for response data, defaults to timezone of request date -parameter. If specified, representation of result dates is converted into specified timezone.

Sample response:

{
    "sn": "DM123412343",
    "label": "John",
    "destinations": [
        {
            "country": "FI",
            "iccid": "8935806111212584189",
            "data": [
                {
                    "date": "2012-12-22T01+11:00",
                    "consumption": 432
                }
            ]
        },
        {
            "country": "SE",
            "iccid": "4835806111212512345",
            "data": [
                {
                    "date": "2012-12-22T01+11:00",
                    "consumption": 132
                },
                {
                    "date": "2012-12-22T02+11:00",
                    "consumption": 42
                }
            ]
        }
    ]
}

Field details

  • sn - serial number of associated device
  • label - optional label of device
  • destinations - statistics of active destinations/countries of device
  • country - Country-code in ISO 3166-1 alpha-2 -format
  • iccid - ICCID of SIM card in question
  • data - daily consumption as list of date-consumption pairs
  • date - Timestamp of record in date+hour+offset (’yyyy-MM-dd’T’HHZZ’) ISO8601 -format.
  • consumption - data consumption during presented hour in kilobytes (1 kilobyte 1024 bytes)

Example for cUrl -command line tool

curl -Gs 'https://goodspeed.io/partner/api/v1/devices/DM123412343/consumption?date=2012-12-12T%2B03:00&timezone=%2B00:00' \
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Get an overview of data consumption over several devices

Data consumption overview for a set of devices for a given time period. Consumption reported as total sum for each day using per destination timezone offset. The "start" and "end" parameters are mandatory. The API endpoint allows access to 180 days old usage data with maximum period between "start" and "end" dates in a single request being 60 days. The "device" parameter can be included in the request multiple times to define the subset of devices (serial numbers) for which the data consumption overview report is generated. If the "device" parameter is omitted, the report is generated over all the devices associated with the account during the requested period (this may take some time if the account is associated with large number of devices).

Note! This API endpoint is asynchronous. The first time a request is received from a client a 202 Accepted response is returned (with a location header). The client is expected to retry the request using the url returned in the location header until it gets a 200 OK response with the payload described below in the body of the response. The client should not poll the location url in a busy-loop, but implement a short wait between subsequent requests.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/devices/all/consumption

Parameters

  • timezone - Optional user-defined timezone for response data. Default timezone is UTC.
  • start - Start date in date+offset (‘yyyy-MM-dd’T’ZZ’) ISO8601-format
  • end - End date in date+offset (‘yyyy-MM-dd’T’ZZ’) ISO8601-format
  • device - Optional device serial number as string. A single request can contain more than one device-parameters.

Sample response:

[
    {
        "sn": "DM622663135",
        "label": "John",
        "destinations": [
            {
                "country": "FI",
                "iccid": "8935806111212576518",
                "data": [
                    {
                        "date": "2012-12-22T+02:00",
                        "consumption": 432
                    }
                ]
            }
        ]
    },
    {
        "sn": "DM123412343",
        "destinations": [
            {
                "country": "FI",
                "iccid": "8935806111212584189",
                "data": [
                    {
                        "date": "2012-12-22T+02:00",
                        "consumption": 432
                    }
                ]
            },
            {
                "country": "SE",
                "iccid": "4835806111212512345",
                "data": [
                    {
                        "date": "2012-12-13T+02:00",
                        "consumption": 132
                    },
                    {
                        "date": "2012-12-14T+02:00",
                        "consumption": 42
                    }
                ]
            }
        ]
    }
]

Field details

  • sn - serial number of associated device
  • label - optional label of device
  • destinations - statistics of active destinations/countries of device
    • country - Countrycode in ISO 3166-1 alpha-2 -format
    • iccid - ICCID of SIM card in question
    • data - daily consumption as list of date-consumption pairs
    • date - Date of record in date+offset (‘yyyy-MM-dd'T'ZZ’) ISO8601 -format.
    • consumption - data consumption during presented day in kilobytes (1024 bytes)

Example 1: Get consumption overview for 3 devices for the past (UTC) week

curl -Gs 'https://goodspeed.io/partner/api/v1/devices/all/consumption?start=2014-01-03T%2B00:00&end=2014-01-09T%2B00:00&device=CD8187653411&device=CD8187653412&device=CD8187653404'
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Example 2: Get consumption overview for all devices for January 2014 (UTC), convert days to +03:00 days in results.

curl -Gs 'https://goodspeed.io/partner/api/v1/devices/all/consumption?start=2014-01-01T%2B00:00&end=2014-01-31T%2B00:00&timezone=%2B03:00'
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed

Events for given time period

List all account's events for a given time period. The query is executed by giving a set of criteria, for example a date range and a set of other, optional parameters. Returned events contain a type that determines what has happened and a reference that tells the relation. For instance for destination daypass payment events, the reference tells the serial number of the device that consumed the daypass. Reference can be also used as search criteria. A list of supported events and list of data provided is shown below.

The API endpoint allows access to 365 days old usage data. The query has a limitation of 1000 results. If the limit is reached, the result set is cut even if more results were available.

Request method

GET

Request URL

https://goodspeed.io/partner/api/v1/events

Parameters

  • timezone - Optional user-defined timezone for response data. Default timezone is UTC.
  • start - Start date in date+offset (‘yyyy-MM-dd’T’ZZ’) ISO8601-format
  • end - End date in date+offset (‘yyyy-MM-dd’T’ZZ’) ISO8601-format
  • reference - Optional reference search criteria. See meaning of the reference parameter in table below. A single request can contain more than one reference-parameters. If omitted, ignores this criteria (returns events for all devices)

Sample response:

[
    {
        "date": "2016-12-01T09:27:45+02:00",
        "type": "DAYPASS",
        "reference": "DM123412343",
        "data": {
            "country": "FI",
            "price": 7.20,
            "currency": "EUR"
        }
    },
    {
        "date": "2016-12-01T11:51:31+02:00",
        "type": "REFILL",
        "description": "DM123412343",
        "data": {
            "country": "FI",
            "price": 7.20,
            "currency": "EUR"
        }
    }
]

Field details

  • date - time of the event in ISO8601 -format
  • type - type of the event, see table in below chapter
  • reference - event reference, see table in below chapter
  • data - event type -specific data, see table in below chapter
    • country - country code where the event occurred (Only for events where this is applicable)
    • price - price, including VAT (Only in events that contain payment)
    • currency - currency code of the price (Only in events that contain payment)

List of event types and details

Type Explanation Reference Data
DAYPASS One daypass has been consumed Device serial nr. country (always), price and currency (if payment was involved)
REFILL Daypass has been refilled Device serial nr. country (always), price and currency (if payment was involved)

Client applications should prepare for the possibility for more events being added without prior notice. A good approach would be to handle the events according to its type.

Example

Get consumption overview for all devices for January 2014 (UTC), convert days to +03:00 days in results.

curl -Gs 'https://goodspeed.io/partner/api/v1/events?start=2014-01-01T%2B00:00&end=2014-01-31T%2B00:00&timezone=%2B03:00'
    -H 'X-Goodspeed-Username: john.doe@example.com' \
    -H 'X-Goodspeed-API-Token: 12345678901234567890123456789012' \
    --compressed