HotspotSystem API documentation

SSL only

We require that all requests are done over SSL.

UTF-8 encoding

Every string passed to and from the API needs to be UTF-8 encoded.

Date format

All dates in the API are strings in the following format:

"2013-05-21 17:53:39"

The API uses HTTP Basic Authentication, which is secure since all requests use SSL.

The API key can be specified in the authentication section of the request. If your language requires a username and password, enter the API key in the username and leave the password empty.

Your API key can be generated from the Control Center > Tools & Settings > API Keys menu.

Every request includes an HTTP status code with the result. The status code should examined before the response. In most cases, the response body will contain further details.

Error codes

Sample JSON return value

{
  "success": false,
  "error": {
      "code": 401,
      "message": "Authorization Required"
  }
}

Sample cURL code

curl -v -H "Content-Type: application/json" -X GET -u <api_key>:x https://api.hotspotsystem.com/v1.0/locations.json

More on cURL command line tool

Sample PHP code

<?
    ini_set('display_errors', 1);
    error_reporting(-1);

    $resCurl = curl_init();
    
    curl_setopt($resCurl, CURLOPT_URL, "https://api.hotspotsystem.com/v1.0/locations.json");
    curl_setopt($resCurl, CURLOPT_USERPWD, "/*api_key*/");
    curl_setopt($resCurl, CURLOPT_TIMEOUT, 30);
    curl_setopt($resCurl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($resCurl, CURLOPT_VERBOSE, true);

    $sReturnValue = curl_exec($resCurl);  
    $aResponseInfo = curl_getinfo($resCurl);
?>

More on PHP's Client URL Library

Description

Returns the registered locations.

URL Structure

https://api.hotspotsystem.com/<version>/locations.<format>

• version The API's version number. v1.0
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the registered locations.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 1,
        "offset": 2,
        "total_count": 4,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/locations.json?limit=1&offset=2",
            "next_link": "https://api.hotspotsystem.com/v1.0/locations.json?limit=1&offset=3",
            "previous_link": "https://api.hotspotsystem.com/v1.0/locations.json?limit=1&offset=1"
        }
    },
    "results": [
        {
            "location_id": "1",
            "location_name": "Budapest",
            "address": "Váci Way",
            "city": "Budapest",
            "state": null,
            "zip": "1133",
            "country_code": "HU"
        }
    ]
}

Return value definitions

field	description
limit	The requested number of objects returned by the server.
offset	The requested start point of the region of objects.
total_count	Total length of the collection.
self_link	Query link that returns the current region of objects.
next_link	Query link that returns the next region of objects, if present.
previous_link	Query link that returns the previous region of objects, if present.
location_id	Unique identifier of the location.
location_name	Common name of the location.
address	Street name with house number.
city	City name.
state	County name.
zip	Postal code.
country_code	Two-letter country code.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the customers.

URL Structure

https://api.hotspotsystem.com/<version>/customers.<format>

• version The API's version number. v1.0
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the customers.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 100,
        "offset": 0,
        "total_count": 1,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/subscribers.json?limit=100&offset=0"
        }
    },
    "results": [
        {
            "customer_id": "1",
            "customer_name": "John Doe",
            "user_name": "jdoe",
            "email": "jdoe@example.net",
            "company_name": null,
            "address": "Váci Way",
            "city": "Budapest",
            "state": null,
            "zip": "1133",
            "country_code": "HU",
            "phone": "+36 1 000 0000",
            "registered_at": "2013-05-21 17:53:39"
        }
    ]
}

Return value definitions

field	description
customer_id	Unique identifier of the user.
customer_name	Full name of the person.
user_name	User name of the person.
email	E-mail address of the user.
company_name	Type of business entity associated with the person.
address	Street name with house number.
city	City name.
state	County name.
zip	Postal code.
country_code	Two-letter country code.
phone	Cell phone number of the user.
registered_at	Date and time of the creation of the user.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the customers at the requested location.

URL Structure

https://api.hotspotsystem.com/<version>/locations/<id>/customers.<format>

• version The API's version number. v1.0
• id A location's or a group of locations unique identifier. 1 or g1
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the customers at the requested location.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 100,
        "offset": 0,
        "total_count": 1,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/subscribers.json?limit=100&offset=0"
        }
    },
    "results": [
        {
            "customer_id": "1",
            "customer_name": "John Doe",
            "user_name": "jdoe",
            "email": "jdoe@example.net",
            "company_name": null,
            "address": "Váci Way",
            "city": "Budapest",
            "state": null,
            "zip": "1133",
            "country_code": "HU",
            "phone": "+36 1 000 0000",
            "registered_at": "2013-05-21 17:53:39"
        }
    ]
}

Return value definitions

field	description
customer_id	Unique identifier of the user.
customer_name	Full name of the person.
user_name	User name of the person.
email	E-mail address of the user.
company_name	Type of business entity associated with the person.
address	Street name with house number.
city	City name.
state	County name.
zip	Postal code.
country_code	Two-letter country code.
phone	Cell phone number of the user.
registered_at	Date and time of the creation of the user.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the newsletter subscribers.

URL Structure

https://api.hotspotsystem.com/<version>/subscribers.<format>

• version The API's version number. v1.0
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the newsletter subscribers.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 100,
        "offset": 0,
        "total_count": 1,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/subscribers.json?limit=100&offset=0"
        }
    },
    "results": [
        {
            "customer_id": "1",
            "customer_name": "John Doe",
            "user_name": "jdoe",
            "email": "jdoe@example.net",
            "company_name": null,
            "address": "Váci Way",
            "city": "Budapest",
            "state": null,
            "zip": "1133",
            "country_code": "HU",
            "phone": "+36 1 000 0000",
            "registered_at": "2013-05-21 17:53:39"
        }
    ]
}

Return value definitions

field	description
customer_id	Unique identifier of the user.
customer_name	Full name of the person.
user_name	User name of the person.
email	E-mail address of the user.
company_name	Type of business entity associated with the person.
address	Street name with house number.
city	City name.
state	County name.
zip	Postal code.
country_code	Two-letter country code.
phone	Cell phone number of the user.
registered_at	Date and time of the creation of the user.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the newsletter subscribers at the requested location.

URL Structure

https://api.hotspotsystem.com/<version>/locations/<id>/subscribers.<format>

• version The API's version number. v1.0
• id A location's or a group of locations unique identifier. 1 or g1
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the newsletter subscribers at the requested location.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 100,
        "offset": 0,
        "total_count": 1,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/subscribers.json?limit=100&offset=0"
        }
    },
    "results": [
        {
            "customer_id": "1",
            "customer_name": "John Doe",
            "user_name": "jdoe",
            "email": "jdoe@example.net",
            "company_name": null,
            "address": "Váci Way",
            "city": "Budapest",
            "state": null,
            "zip": "1133",
            "country_code": "HU",
            "phone": "+36 1 000 0000",
            "registered_at": "2013-05-21 17:53:39"
        }
    ]
}

Return value definitions

field	description
customer_id	Unique identifier of the user.
customer_name	Full name of the person.
user_name	User name of the person.
email	E-mail address of the user.
company_name	Type of business entity associated with the person.
address	Street name with house number.
city	City name.
state	County name.
zip	Postal code.
country_code	Two-letter country code.
phone	Cell phone number of the user.
registered_at	Date and time of the creation of the user.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the pre-paid vouchers.

URL Structure

https://api.hotspotsystem.com/<version>/vouchers.<format>

• version The API's version number. v1.0
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the pre-paid vouchers.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 1,
        "offset": 2,
        "total_count": 26,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=2",
            "next_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=3",
            "previous_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=1"
        }
    },
    "results": [
        {
            "serial": "1229604629-75347",
            "voucher_code": "1h-651978",
            "limit_tl": -1,
            "simultaneous_use": 1,
            "limit_dl": -1,
            "limit_ul": -1,
            "usage_exp": "1 day",
            "validity": 30,
            "price_enduser": "0 HUF"
        }
    ]
}

Return value definitions

field	description
serial	Unique identifier of the voucher.
voucher_code	Users must type in this additional code.
limit_tl	Traffic limit in bytes. If the return value is -1, no location context is set.
simultaneous_use	The number of simultaneous connections allowed.
limit_dl	Download limit in bytes. If the return value is -1, no location context is set.
limit_ul	Upload limit in bytes. If the return value is -1, no location context is set.
usage_exp	Expiration time left from today.
validity	Can be used for the amount of minutes returned.
price_enduser	The price and currency it was sold for.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Returns the pre-paid vouchers at the requested location.

URL Structure

https://api.hotspotsystem.com/<version>/locations/<id>/vouchers.<format>

• version The API's version number. v1.0
• id A location's or a group of locations unique identifier. 1 or g1
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• limit Limits the number of objects returned by the server. Defaults to 100.
• offset Defines the starting point of the returned object range. Defaults to 0. The end point of the range is offset + limit.
• sort The returned objects can be sorted by any field. name To reverse the sorting direction, prepend a minus sign to the field's name. -name
• fields You can define, which fields must be included in the response. The value of the parameter is a list of comma separated field names. name,type,datetime

Returns

Returns the pre-paid vouchers at the requested location.

Sample JSON return value

{
    "success": true,
    "metadata": {
        "limit": 1,
        "offset": 2,
        "total_count": 26,
        "links": {
            "self_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=2",
            "next_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=3",
            "previous_link": "https://api.hotspotsystem.com/v1.0/vouchers.json?limit=1&offset=1"
        }
    },
    "results": [
        {
            "serial": "1229604629-75347",
            "voucher_code": "1h-651978",
            "limit_tl": -1,
            "simultaneous_use": 1,
            "limit_dl": -1,
            "limit_ul": -1,
            "usage_exp": "1 day",
            "validity": 30,
            "price_enduser": "0 HUF"
        }
    ]
}

Return value definitions

field	description
serial	Unique identifier of the voucher.
voucher_code	Users must type in this additional code.
limit_tl	Traffic limit in bytes. If the return value is -1, no location context is set.
simultaneous_use	The number of simultaneous connections allowed.
limit_dl	Download limit in bytes. If the return value is -1, no location context is set.
limit_ul	Upload limit in bytes. If the return value is -1, no location context is set.
usage_exp	Expiration time left from today.
validity	Can be used for the amount of minutes returned.
price_enduser	The price and currency it was sold for.

Error codes

code	description
1001	Insufficient privileges.
1002	Invaild field parameter.
1003	Invalid request detected.
1004	Invalid filter parameter.
1005	Invalid sort parameter.

Description

Generate a voucher code on the fly against voucher credits.

URL Structure

https://api.hotspotsystem.com/<version>/locations/<id>/generate/voucher.<format>

• version The API's version number. v1.0
• id A location ID where the voucher credit will be deducted from (if the location has a Free Voucher subscription, credits will be deducted from the subscription credits, otherwise it will be deducted from the Pay As You Go credits). If a pay per use voucher is generated the system deducts 2 voucher credits, for free vouchers the system deducts 1 credit. 1
• format The type of data that you're expecting back from the server. json or xml

Method

GET

Parameters

• validity A location ID or a location group ID where the voucher can be activated. If there is no validity parameter specified, the voucher can be activated in the same location as the <id> parameter..
• package ID of a custom package which is used to define the voucher parameters. If no package is specified, a voucher code will be generated based on the default free access of the location.

Returns

Generate a voucher code on the fly against voucher credits.

Sample JSON return value

{
    "success": true,
    "access_code": "1w-6669999"
}

Return value definitions

field	description
access_code	The generated code of the voucher.

Error codes

code	description
1001	Insufficient privileges.
1006	Insufficient voucher credit.
1009	Invalid package ID.
1010	Currency mismatch.
1011	Invalid Location.