Welcome

Welcome to the API available on php.ug!

You can use this API to access Usergroup-Informations for currently active usergroups

We currently have examples for language bindings in PHP but you can consume this API with any language you like. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This API documentation was created with Slate.

Authentication

Currently there’s no authentication. Just consume the API on a fair base and we’ll all get along finely.

Return-Types

This API returns JSON by default, but you can also get serialized PHP-Data when you add .sphp to the endpoint. So to get a serialized array of listtypes you would call the following:

GET https://php.ug/api/rest/listtype.sphp

Usergroup-Types

Get a list of usergroup-Types

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/rest/listtype');

The above command returns JSON structured like this:

[
    {
        "description": "PHP-Usergroups",
        "id": 1,
        "name": "PHP-Usergroups"
    }
]

This endpoint retrieves all Usergroup-Types available. The API is already setup to serve more than PHP-Usergroups, but currently there are only PHP-Usergroups available.

HTTP Request

GET https://php.ug/api/rest/listtype

Get a specific Usergroup-Type

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/rest/listtype/<ID>');

The above command returns JSON structured like this:

{
    "error": null,
    "groups": [
        {
            "contacts": [
                {
                    "cssClass": "fa-twitter fa",
                    "name": "phpugffm",
                    "type": "Twitter",
                    "url": "http://twitter.com/phpugffm"
                }
            ],
            "country": "DE",
            "icalendar_url": "http://www.phpugffm.de/?ical=1",
            "id": 1,
            "latitude": 50.11395,
            "longitude": 8.67922,
            "name": "Frankfurt",
            "shortname": "ffm",
            "state": 1,
            "tags": [
                {
                    "description": "obviously",
                    "name": "PHP"
                }
            ],
            "ugtype": {
                "description": "PHP-Usergroups",
                "id": 1,
                "name": "PHP-Usergroups"
            },
            "url": "http://phpugffm.de"
        }
    ],
    "list": {
        "description": "PHP-Usergroups",
        "id": 1,
        "name": "PHP-Usergroups"
    }
}

This endpoint retrieves a specific Listtype. This includes a list of all usergroups.

Note: This will change in the near future!

HTTP Request

GET https://php.ug/api/rest/listtype/<ID>

Usergroups

Get details of a certain usergroup

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/rest/usergroup/<ID>');

The above command returns JSON structured like this:

{
    "error": null,
    "group": {
        "contacts": [
            {
                "cssClass": "fa-twitter fa",
                "name": "phpugffm",
                "type": "Twitter",
                "url": "http://twitter.com/phpugffm"
            }
        ],
        "icalendar_url": "http://www.phpugffm.de/?ical=1",
        "id": 1,
        "latitude": 50.11395,
        "longitude": 8.67922,
        "name": "Frankfurt",
        "shortname": "ffm",
        "state": 1,
        "tags": [
            {
                "description": "obviously",
                "name": "PHP"
            }
        ],
        "ugtype": {
            "description": "PHP-Usergroups",
            "id": 1,
            "name": "PHP-Usergroups"
        },
        "url": "http://phpugffm.de"
    }
}

This endpoint retrieves the details of one specific usergroup. The parameter ID has to be the numeric id of the usergroup

HTTP Request

GET https://php.ug/api/rest/usergroup/<ID>

Additional Usergroup-Informations

Get the next event of a usergroup

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/v1/usergroup/nextEvent/<SHORTNAME>');

The above command returns JSON structured like this:

{
    "description": "",
    "end": "Thu, 24 Mar 2016 20:30:00 +0000",
    "location": "Sitewards GmbH",
    "start": "Thu, 24 Mar 2016 18:00:00 +0000",
    "summary": "PHPUGFFM II / 2016 - Sitewards GmbH - 24 Mrz 16 19:00",
    "url": "http://www.phpugffm.de/veranstaltungen-2/phpugffm-ii-2016/"
}

This endpoint retrieves the next event that a ausergroup scheduled in their calendar. As we can only grab those events, when the usergroup provides a link to their event-calendar, not all usergroups will return information on that endpoint!

HTTP Request

GET https://php.ug/api/v1/usergroup/nextEvent/<SHORTNAME>

Query Parameters

Parameter	Value
SHORTNAME	The shortname of a Usergroup

Location-based information

Groups next to a location

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/v1/location/nextGroups?latitude=50.0&longitude=8.0&distance=20');

The above command returns JSON structured like this:

{
    "groups": {
        "currentLocation": {
            "latitude": "50.0",
            "longitude": "8.0"
        },
        "groups": [
            {
                "contacts": [
                    {
                        "name": "phpugrhh",
                        "service": "Twitter",
                        "uri": "http://twitter.com/phpugrhh"
                    }
                ],
                "distance": "9.62303526009361",
                "icalendar_url": "",
                "latitude": 49.9999,
                "longitude": 8.26944,
                "name": "Rheinhessen",
                "shortname": "mainz",
                "uri": "",
                "url": "http://phpug-rheinhessen.de/"
            }
        ]
    }
}

Get a list of usergroups depending on a geolocation. This returns a list of groups within a radius of distance around the geolocation defined by latitude and longitude. you can also retrieve the next count usergroups around the geolocation.

When you specify both distance and count the first that will apply limits the number of returned groups.

HTTP Request

GET https://php.ug/api/v1/location/nextGroups

Query Parameters

Parameter	Reqired	Description
latitude	*	The latitude of the center
longitude	*	The longitude of the center
distance		The distance around the center in which to look. The distance has to be given in kilometers!
count		The number of usergroups to return.

Calendar Informations

Get Events of groups

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/v1/calendar/list');

The above Command returns JSON as follows

[
    {
        "description": "Here might be a description of the event",
        "end": "2016-01-21T20:30:00+00:00",
        "start": "2016-01-21T18:00:00+00:00",
        "title": "[Frankfurt] PHPUGFFM I / 2016 -  - 21 Jan 16 19:00"
    }
]

$client = new GuzzleHttp\Client();
$result = $client->request('GET', 'https://php.ug/api/v1/calendar/list', [
    'header' => ['Accept' => 'text/calendar']
]);

The above Command returns an iCalendar-File as follows

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Sabre//Sabre VObject 4.0.3//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
UID:321eecbc-4ad1-4c08-9d65-f993b5749afc
DTSTART:20160121T180000Z
DTEND:20160121T203000Z
DTSTAMP:20151020T193220Z
LOCATION:
URL;VALUE=URI:http://www.phpugffm.de/veranstaltungen-2/phpugffm-i-2016/
SUMMARY:[Frankfurt] PHPUGFFM I / 2016 -  - 21 Jan 16 19:00
END:VEVENT
END:VCALENDAR

Gets all the known events that are listed in the groups calendars. The groups are selected like described in Groups next to a location.

When no location is provided a list of all calendar-entries is returned!

HTTP Request

GET https://php.ug/api/v1/calendar/list

Query Parameters

Parameter	Reqired	Description
latitude		The latitude of the center
longitude		The longitude of the center
distance		The distance around the center in which to look. The distance has to be given in kilometers!
count		The number of usergroups to return.

Errors

The php.ug-API currently does not use Error-codes

The returned result always contains a field error with either content NULL or a string with an error-message.