Haunted Planet
Login:


sign up | forgot password

Quick Links

API Reference

(api intro here)


getAvailableCases(email, latitude, longitude, number, radius)

This function returns a JSON array with the cases available to the player identified by <email> and visible within <radius> meters from the location identified by <latitude> and <longitude>. A maximum of <number> cases are returned. The parameters are encoded as a JSON array and the function invoked via HTTP POST.

The method returns a JSON array with two elements: <status> and <data>. The <status> element is either 'success' in which case the <data> element contains an array with the available cases (which may be empty, if no cases were in range), or 'error' in which case the <data> element contains a short error message that the client can print. The short message does not reveal too much information about the server.

URL

http://www.hauntedplanet.com/api/getAvailableCases

Example Request

{
    "email": "someone@somewhere.com",
    "latitude": 53.34727,
    "longitude": -6.25937,
    "number": 10,
    "radius": 100000
}

Example Responses

{
    "status": "success",
    "data": [
        {
            "id": "e6a36ef906374465ad7341d4a9e54f65",
            "case_name": "Pirate Ghost Hunt",
            "author_name": "Pirates of Emerson",
            "category": "Featured",
            "location": {
	        "latitude": 53.342283,
                "longitude": -6.254246
            },
	    "locality": "Trinity College",
            "description": "Come find the seven pirate ghosts in Trinity College.  Seven ghostly pirates roam the city - who are these mysterious specters?",
            "pegi_rating": "12",
            "pegi_descriptors": [
                "fear",
                "online"
            ],
            "completion": "You've solved the pirate mystery at the Alameda County Fair and found the pirates' hidden treasure!",
            "icon": {
                "url": "http://dl.dropbox.com/u/35154964/MockData/iconname.png",
                "modified": 1318547527339,
                "size": 305145
            }
        },
        {
            "id": "3a7ea351537e42518bb17558de8d4f33",
            "case_name": "Vampire Mystery",
            "author_name": "Haunted Planet",
            "category": "Universal",
            "location": {
                "latitude": null,
                "longitude": null
            },
	    "locality": null,
            "description": "Vampires everywhere - oh no!",
            "pegi_rating": "16",
            "pegi_descriptors": [
                "fear",
                "sex",
                "online"
            ],
            "completion": "You've rid the area of vampires - congratulations!",
            "icon": {
                "url": "http://no-icon-yet/",
                "modified": 0,
                "size": 0
            }
        }
    ]
}
{
  "status": "error",
  "data": "only POST accepted"
}

getCase(email, latitude, longitude, case_id)

This function returns a GHML case specification for a given <case_id>. The function checks that the player actually has privileges to access the case, which is what the player's <email> address is required for. If the case is a location-specific one, the <latitude> and <longitude> parameters are ignored, but if it is location-agnostic, the server tweaks the case specification such that its points of interest reside in the vicinity of the <latitude> and <longitude> given. The parameters are encoded as a JSON array and the function invoked via HTTP POST.

The method returns a JSON array with two elements: <status> and <data>. The <status> element is either 'success' in which case the <data> element contains the base64-encoded GHML document with the case spefication, or 'error' in which case the <data> element contains a short error message that the client can print. The short message does not reveal too much information about the server.

The reason that we base64-encode the GHML document is that json_encode() doesn't seem to handle utf-8 encoded data properly for PHP < 5.4.

URL

http://www.hauntedplanet.com/api/getCase

Example Request

{
    "email": "someone@somewhere.com",
    "latitude": 53.4079,
    "longitude": -6.9434,
    "case_id": "e6a36ef906374465ad7341d4a9e54f65"
}

Example Responses

{
    "status": "success",
    "data": "PD94bWwgdmVyc ... U+Cg=="
}
{
  "status": "success",
  "data": "fail_access_denied"
}


getLocality(latitude, longitude)

This function returns a JSON-encoded text string with the name of the locality specified by the coordinates. The text strings are intended to be suitable to print as information to a player about where a case is located, or what the game thinks the player's current location is. The function uses the Google reverse geocoding API. The parameters are encoded as a JSON array and the function invoked via HTTP POST.

The method returns a JSON array with two elements: <status> and <data>. The <status> element is either 'success' in which case the <data> element contains a the locality string, or 'error' in which case the <data> element contains a short (unencoded) message that the client can print. The short message does not reveal too much information about the server.

URL

http://www.hauntedplanet.com/api/getLocality

Example Request

{
    "latitude": 37.73440,
    "longitude": -122.435707,
}

Example Responses

{
    "status": "success",
    "data": "Glen Park, San Francisco"
}
{
  "status": "error",
  "data": "only POST accepted"
}

checkDeviceRegistration(device_id, email)

This function is used by the mobile app to verify whether it's okay for the game to run on the given device with <device_id>. We need it because we can ask people for their <email> address when they start the app first, but we don't want them to go through a full registration process. For that reason, we need to check that they don't pick an email that is already registered to another handset. The parameters are encoded in a JSON array and the function invoked via HTTP POST.

The method returns a JSON array with two elements: <status> and <data>. The <status> element is either 'success' (meaning that the request was processed) in which case the <data> element contains a string that indicates whether the mobile app should be allowed to run or not. Possible values for the <data> element in this case are 'ok_already_registered' which indicates that the mobile device is already registered to the email address in question; 'ok_registration_created' which indicates that the device had not been seen before but is now registered to the email in question; 'fail_conflicting_registration' which indicates that the device in question is registered to a different email address (and therefore the app should ask the user to authenticate); or 'fail_unregistered_device' which indicates that it's a new device for an existing user (in which case the app should as the user to authenticate too). Effectively, any registrations that have to do with an existing account need to get authenticated in order to prevent unauthorized access to the account's data.

If something goes wrong during the processing of the request, the <status> element is set to 'error' and the <data> element contains a short error message that the client can print. The short message does not reveal too much information about the server.

URL

http://www.hauntedplanet.com/api/checkDeviceRegistration

Example Request

{
    "device_id": "34839993832",
    "email": "someone@somewhere.com"
}

Example Responses

{
    "status": "success",
    "data": "ok_already_registered"
}
{
    "status": "success",
    "data": "fail_conflicting_registration"
}
{
    "status": "error",
    "data": "server unavailable"
}

changeDeviceRegistration(device_id, email, password)

This function is used by the mobile app to change the registration of a device when this is required. (For further info, see also checkDeviceRegistration().) A client must use this function if it wants to register a device with <device_id> to an <email> account that already exists. The parameters are encoded in a JSON array and the function invoked via HTTP POST.

The method returns a JSON array with two elements: <status> and <data>. The <status> element is either 'success' (meaning that the request was processed) in which case the <data> element contains a string that may be 'ok_changed' to indicate that the device in question is now associated with the <email> account; or 'ok_added' to indicate that the device has been added to those registered for this player; or it may be 'fail_authentication_error' to indicate that the email/password combination given was not valid.

If something goes wrong during the processing of the request, the <status> element is set to 'error' and the <data> element contains a short error message that the client can print. The short message does not reveal too much information about the server.

URL

http://www.hauntedplanet.com/api/changeDeviceRegistration

Example Request

{
    "device_id": "34839993832",
    "email": "someone@somewhere.com"
    "password": "secret"
}

Example Responses

{
    "status": "success",
    "data": "ok_changed"
}
{
    "status": "success",
    "data": "fail_authentication_error"
}
{
    "status": "error",
    "data": "server unavailable"
}