org.gbanga.api
Interface API

public interface API

The public Gbanga Puppetmaster API which is publicly available. The URL to access documentation and to communicate with the RESTful API is at http://api.gbanga.com.

Author:

Matthias

Field Summary

static short	ANDROID Android phone category.
static short	ANDROID_PLAT Android platform.
static short	BADA bada platform.
static short	BLACKBERRY BlackBerry phone category.
static short	BLACKBERRY_PLAT BlackBerry platform.
static int	BUG_SEVERITY_CRITICAL A critical bug.
static int	BUG_SEVERITY_ENHANCEMENT Not a bug, but a possible enhancement.
static int	BUG_SEVERITY_MAJOR A major bug.
static int	BUG_SEVERITY_MINOR A minor bug.
static int	BUG_SEVERITY_NORMAL A medium bug.
static int	BUG_SEVERITY_TRIVIAL A trivial bug.
static int	DEFAULT_EVENTS_AT_N The default number of local Events that are returned when calling getEventsAt(String).
static int	DEFAULT_FEATURED_STORIES_N The default number of featured Story objects that are requested with getFeaturedStories().
static int	DEFAULT_GLOBAL_EVENTS_N The number of events to list in a getGlobalEvents() call.
static int	DEFAULT_HIGHSCORE_FIRST Parameter to indicate the rank of the first entry in the highscore.
static int	DEFAULT_HIGHSCORE_N Parameter to indicate the number of entries in the highscore.
static byte	DEFAULT_HIGHSCORE_TYPE Default value for highscore type (is one of the following values: daily, weekly, monthly, annual or all times).
static int	DEFAULT_MOST_POPULAR_N The default number of the most popular Tags that are requested with getMostPopular().
static int	DEFAULT_NEWCOMERS_N The default number of newcomers that are requested with getNewcomers().
static byte	DROP Drop a Gbangoo.
static int	HIGHSCORE_TYPE_EVER Parameter to get the highscore of all times.
static int	HIGHSCORE_TYPE_OFDAY Parameter to get the daily highscore.
static int	HIGHSCORE_TYPE_OFMONTH Parameter to get the monthly highscore.
static int	HIGHSCORE_TYPE_OFWEEK Parameter to get the weekly highscore.
static int	HIGHSCORE_TYPE_OFYEAR Parameter to get the annual highscore with.
static short	IPHONE iPhone phone category.
static short	IPHONE_PLAT iPhone platform.
static byte	LIFT Lift a Gbangoo.
static short	MAEMO Maemo platform.
static int	MAX_EVENTS_AT_N The maximum number of local Events that can be retrieved with getEventsAt(String, int).
static int	MAX_FEATURED_STORIES_N The maximum number of featured Story objects that can be requested with getFeaturedStories(int).
static int	MAX_GLOBAL_EVENTS_N Maximum value for event global requests.
static int	MAX_HIGHSCORE_N Maximum value for highscore entry count.
static int	MAX_MESSAGES This is the maximum number of messages returned by the methods getConversationWithGbangoo(String, long) and getConversationWithPlayer(String, String).
static int	MAX_MESSAGES_N The maximum number of messages returned by the API methods such as getShouts(String) and getStatusFeed(String).
static int	MAX_MOST_POPULAR_N The maximum number of the most popular Tags objects that can be requested with getMostPopular(int).
static int	MAX_NEWCOMERS_N The maximum of newcomers that can be requested with getNewcomers(int).
static short	MOTOROLA Motorola phone category.
static short	MOTOROLA_PLAT Motorola platform.
static short	NOKIA Nokia phone category.
static short	OPEN_MOKO Open Moko platform.
static short	OTHER Other phone category.
static int	PIECE_AT_RANDOM_TILE Specifies to piece a Tag to a random tile within the current Cell of the logged in Player (this is standard behaviour on clients).
static int	PIECE_AWAY Specifies to piece a Tag to nowhere in order to dispose it from the current Pocket.
static short	SAMSUNG Samsung phone category.
static short	SONYERICSSON Sony Ericsson phone category.
static short	SONYERICSSON_PLAT Sony Ericsson platform.
static short	SYMBIAN_S60 Symbian S60 platform.
static short	UIQ UIQ platform.
static short	UNKNOWN The phone model was not listed so the platform is unknown.
static short	UNSUPPORTED Unsupported platform.
static int	VERSION The major version number of this API.
static short	WINDOWS_MOBILE Windows Mobile phone category.
static short	WINDOWS_MOBILE_PLAT Windows Mobile platform.

Method Summary

Trade	abort(java.lang.String sessionKey, long tradeId) Decline an incoming trade offer.
Trade	accept(java.lang.String sessionKey, long tradeId) Accept an incoming trade offer.
Player	acceptFriendship(java.lang.String sessionKey, java.lang.String player) Accepts the friendship offer of another player.
Trade	addToOffer(java.lang.String sessionKey, long tradeId, long offeredGoodId, long requestedGoodId) Add goods to the indicated offer.
Player	adjustInterests(java.lang.String sessionKey, boolean play, boolean collecting, boolean trading, boolean events, boolean networking, boolean travel, boolean dating) Update your keywords of interest.
Gbangoo	beamGbangoo(java.lang.String sessionKey, long gbangooId, java.lang.String cellName) Teleport a Gbangoo to a given cell.
Infrastructure	beamInfrastructure(java.lang.String sessionKey, long infrastructureId, java.lang.String cellName) Teleport an infrastructure to a given cell.
Resource	beamResource(java.lang.String sessionKey, long resourceId, java.lang.String cellName) Teleport a resource to a given cell.
Player	breakWith(java.lang.String sessionKey, java.lang.String player, java.lang.String lastMessage) Break with a prior friend and, optionally, let him know why.
void	broadcast(java.lang.String sessionKey, java.lang.String message) Sends a Message to all player friends.
Infrastructure	build(java.lang.String sessionKey, long gbangooId, long type, java.lang.String screenname) A Gbangoo starts with a construction of a building of given type at its current location.
Challenge	challenge(java.lang.String sessionKey, long challengerId, long opponentId) Start a match between the initiating challenger and the challenged opponent.
Player	changeSettings(java.lang.String sessionKey, boolean friendCanSeeMyPosition, boolean everybodyCanSeeMyPosition, boolean notifyBySMS, boolean notifyByEmail) Update your privacy sensitive settings.
Tile	clear(java.lang.String sessionKey, long tileId) Remove the indicated tile from the Gbanga world.
void	collectResource(java.lang.String sessionKey, long id) Collects a resource.
long	createAvatar(java.lang.String sessionKey, java.io.InputStream image) Creates a new avatar from the given InputStream.
long	createDescription(java.lang.String sessionKey, java.lang.String text) Creates a new description from the given text.
Gbangoo	createGbangoo(java.lang.String sessionKey, long type, java.lang.String name, long avatar, long description) Creates a Gbangoo.
long	createGbangooType(java.lang.String sessionKey, java.io.InputStream avatar, java.lang.String description, java.lang.String comment) Creates a new Gbangoo type.
Gube	createGube(java.lang.String sessionKey, long tileId, int lifetime, int color) Pulls a Gube at the given location.
Infrastructure	createInfrastructure(java.lang.String sessionKey, long type, java.lang.String name, long avatar, long description) Creates an Infrastructure.
long	createInfrastructureType(java.lang.String sessionKey, java.io.InputStream avatar, java.lang.String description, java.lang.String comment) Creates a new Infrastructure type.
Resource	createResource(java.lang.String sessionKey, long type, short amount) Creates a particular amount of a resource of given type.
long	createResourceType(java.lang.String sessionKey, java.lang.String screenname, java.io.InputStream avatar, java.lang.String description) Creates a new Resource type.
Tag	createTag(java.lang.String sessionKey, long content, long avatar)
Cell	decorate(java.lang.String sessionKey, long cellId, int[] flag) Set the flag for a given cell.
Feature	discover(java.lang.String sessionKey, java.lang.String cellName, float latitude, float longitude, java.lang.String cellFlagString) Creates a new cell based on the the geographical location of a given player.
void	dispose(java.lang.String sessionKey, long goodId) Disposes of the given Good.
FeatureCollection	findOnMap(java.lang.String queryPhrase) Locates the given phrase in Gbanga (Cell name, city name, ZIP code, etc.)
Player	forceFriendship(java.lang.String sessionKey, java.lang.String offerer, java.lang.String receiver) Forces a friendship offer to be sent from one player to another one.
void	free(java.lang.String sessionKey, long entityId) Releases the given entity to be freely available to other Players.
Message[]	getAllMessages(java.lang.String sessionKey) Returns a list with Messages that have not been read by the recieving Player yet.
Cell	getCell(java.lang.String cellName) Retrieves the cell with the given name.
java.lang.String[]	getCellNames(float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Retrieves the names of all cells within the specified area.
Message[]	getConversationWithGbangoo(java.lang.String sessionKey, long gbangoo) Returns the last messages between you and a Gbangoo (max. 5 messages)
Message[]	getConversationWithPlayer(java.lang.String sessionKey, java.lang.String player) Returns the last messages between two players (max.
int	getCountEntitiesWithMemory(java.lang.String sessionKey, java.lang.String key, java.lang.String value) Counts the entities containing a specific entry in the memory db.
java.lang.String	getDownloadLink(java.lang.String sessionKey) Requests a message with the download location for the client software.
EntitiesFromMemory	getEntitiesWithMemory(java.lang.String sessionKey, java.lang.String memkey, java.lang.String value) Gets the entities containing a specific entry in the memory db.
Event[]	getEventsAt(java.lang.String cellname) Assorts a list with local Events at a given Cell.
Event[]	getEventsAt(java.lang.String cellname, int n) Assorts a list with a given number of local Events at a given Cell.
Story[]	getFeaturedStories() Returns a list of featured stories interesting to be displayed on the frontpage.
Story[]	getFeaturedStories(int n) Returns a list of featured stories interesting to be displayed on the frontpage.
Player[]	getFriends(java.lang.String sessionKey) Returns a list with friend Players of a given authenticated Player.
Player[]	getFriendsInDetail(java.lang.String sessionKey) Returns a list with friend Players containing the location if allowed of a given authenticated Player.
Gbangoo	getGbangoo(java.lang.String gbangooName, java.lang.String ownerName) Retrieve a Gbangoo owned by the indicated player.
Gbangoo	getGbangooById(long gbangooId) Retrieve a Gbangoo given its ID.
Gbangoo	getGbangooById(java.lang.String sessionKey, long gbangooId, java.lang.String lang) Retrieve a Gbangoo given its ID containing the description in the player's language.
Event[]	getGlobalEvents() Returns a number of events that take place right now.
Event[]	getGlobalEvents(int n) Returns a number of events that take place right now.
Player[]	getHighscore(int first, int n, byte type) Assorts a list with entries for the given type of highscore with the given number of entries with a given rank.
Infrastructure	getInfrastructure(long infrastructureId) Retrieve an Infrastructure given its ID.
Infrastructure	getInfrastructure(java.lang.String sessionKey, long infrastructureId, java.lang.String lang) Retrieve an Infrastructure given its ID containing the description in the player's language.
int	getLoginType(java.lang.String playerName) Request a membership for the given person with the given details.
FeatureCollection	getMapTile(float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Returns a list of placemarks that are within the specified area.
java.lang.String	getMemory(java.lang.String sessionKey, java.lang.String entityId, java.lang.String key) Return the value of a given key in a given Entity's memory.
Tag[]	getMostPopular() Returns a list with the most popular Tags.
Tag[]	getMostPopular(int n) Returns a gien number of the most popular Tags.
Player[]	getNewcomers() Assorts a list with Players that have recently signed up.
Player[]	getNewcomers(int n) Assorts a list with Players that have recently signed up.
int	getNumCells(float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Gets the number of cells within the specified area.
Player	getPlayer(java.lang.String playerName) Retrieve a player indicated the player name.
Player	getPlayer(java.lang.String sessionKey, java.lang.String playerName) Retrieve a player indicated the player name and extra details if the caller is a friend.
FeatureCollection	getPlayersIn(float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Returns a list of players that are present within the specified area.
FeatureCollection	getPlayersIn(java.lang.String sessionKey, float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Returns a list of players that are present within the specified area.
Pocket	getPocket(java.lang.String sessionKey) Returns the personal pocket.
Pocket	getPocketOf(java.lang.String sessionKey, java.lang.String playerName) Returns the pocket of the given player.
java.lang.String	getPromotion() Returns HTML and Javascript code with a currently promoted subject.
Cell	getRandomCell(float topLatitude, float leftLongitude, float bottomLatitude, float rightLongitude) Retrieves a random cell within the specified area.
java.lang.String[]	getRanking(java.lang.String memkey, int from, int count) Gets the ranking of players according to the natural ordering of values in the players' memory for a given key and rank range.
Resource	getResource(long id) Retrieve a resource given the id.
Resource	getResource(java.lang.String sessionKey, long id, java.lang.String lang) Retrieve a resource given the id containing the description in the player's language..
Message[]	getShouts(java.lang.String sessionKey) Gets the most recent shouts.
Message[]	getStatusFeed(java.lang.String sessionKey) Gets the status feed messages.
Tag	getTag(long id) Retrieve a tag given the id.
Message[]	getUnreadMessages(java.lang.String sessionKey) Returns a list with Messages that have not been read by the recieving Player yet.
java.lang.String	getVersion() Returns a canonical version String including assembly information and server time.
WebHookSubscription[]	getWebHookSubscriptions(java.lang.String sessionKey) Gets all subscriptions to any Web Hook for the given user.
Event[]	getYourEvents(java.lang.String sessionKey) Returns a number of events that are relevant to an authenticated player personally.
Event[]	getYourEvents(java.lang.String sessionKey, int n) Returns a number of events that are relevant to an authenticated player personally.
Good	give(java.lang.String sessionKey, java.lang.String receivingPlayer, long goodId) Transfers the given Good from one Pocket to another Players Pocket.
void	interact(java.lang.String sessionKey, long id) Interact with an infrastructure.
boolean	invite(java.lang.String sessionKey, java.lang.String name, java.lang.String contactInfo) Send an invitation to the given contact.
boolean	isAvailable(java.lang.String name) Checks if the given name is available.
boolean	isEmailAvailable(java.lang.String email) Checks if the given email address is available.
java.lang.String	isFBUidGbangaUsr(long fbuid, java.lang.String fBsessionKey) Checks if the given name is available.
boolean	isPhoneAvailable(java.lang.String phone) Checks if the given (cell) phone number address is available.
boolean	isTimedOut(java.lang.String sessionKey) Checks whether a given session is timed-out.
boolean	isTradable(long entityId) Checks if a given entity is tradable.
java.lang.String	isUDIDGbangaUsr(java.lang.String udid) Checks if the given name is available.
Gube	jump(java.lang.String sessionKey, long gbangooId) A Gbangoo should jump to the current location of the player and produce the prepared Gube.
Feature	locate(java.lang.String sessionKey, float latitude, float longitude) Retrieve the geographical location of a given cell.
WebSession	login(java.lang.String playerName, java.lang.String password) Authenticates and generates a session key.
void	logout(java.lang.String sessionKey) Close a currently open session by indicating the sessionKey.
Message	mail(java.lang.String sessionKey, java.lang.String receivingPlayer, java.lang.String message) Send a Message to a remote Player.
void	makeProductItemAvailableTo(java.lang.String sessionKey, long productItemId, java.lang.String player, boolean available) Collect a resource.
Gbangoo	mine(java.lang.String sessionKey, long gbangooId) A Gbangoo starts mining at its current location.
Event	move(java.lang.String sessionKey, long entityId, long direction) Move a placeable Entity towards a given direction
void	notify(java.lang.String sessionKey, java.lang.String player, java.lang.String title, java.lang.String description, long avatar, boolean shareable) Sends a notification message to a player.
Player	offerFriendship(java.lang.String sessionKey, java.lang.String player, java.lang.String introduction) Offer friendship to another player.
Pocket	pick(java.lang.String sessionKey, long tagId) Pick up a copy of a tag
Tile	piece(java.lang.String sessionKey, long tagId, long tileId) Create a tag at a given position.
Challenge	playCard(java.lang.String sessionKey, long challengeId, long tagId) Play a given card in a given match.
void	playSound(java.lang.String sessionKey, java.lang.String name, long melodyId) Plays a sound on the device of the given Player if logged in and if settings allow.
Trade	postOffer(java.lang.String sessionKey, long tradeId) Sends the created offer to the trading partner.
Trade	prepareOffer(java.lang.String sessionKey, java.lang.String partnerName) Prepare a trade (initial offer or re-offer) with a given player.
Cell	rateCell(java.lang.String sessionKey, long cellId, byte rating, java.lang.String comment) Rate a given cell.
Tag	rateTag(java.lang.String sessionKey, long tagId, byte rating, java.lang.String comment) Vote for the rating of a Cell.
void	register(java.lang.String playerName, java.lang.String password, java.lang.String cellPhone, java.lang.String email, java.lang.String model, java.lang.String language, java.lang.String method) Request a membership for the given person with the given details.
void	registerFB(java.lang.String playerName, java.lang.String fbuid, java.lang.String fbsession, java.lang.String model, java.lang.String language, java.lang.String method) Request a membership for the given person with the given details.
void	registerFQ(java.lang.String playerName, java.lang.String fquid, java.lang.String fbsession, java.lang.String model, java.lang.String language, java.lang.String method) Request a membership for the given person with the given details.
void	registerLess(java.lang.String playerName, java.lang.String iphoneid, java.lang.String model, java.lang.String language, java.lang.String method) Register a player with the iphone id as the identifier.
void	registerTwitter(java.lang.String playerName, java.lang.String tuid, java.lang.String fbsession, java.lang.String model, java.lang.String language, java.lang.String method) Request a membership for the given person with the given details.
void	remindPassword(java.lang.String phoneOrEmail) Request a password reminder message to an email address or a cell phone.
void	removeMemory(java.lang.String sessionKey, java.lang.String entityId, java.lang.String key) Remove a key-value pair from a Entity's memory.
Cell	renameCell(java.lang.String sessionKey, long cellId, java.lang.String name) Gives a new name to a given cell.
int	reportBug(java.lang.String author, java.lang.String content, int severity) Post a bug report indicating the author, a problem description and the severity.
Report	reportPlayer(java.lang.String sessionKey, java.lang.String player, java.lang.String explanation) Report an incident about a player that didn't comply with the regulations (rudeness in chat messages, privacy tricks, fraud, creating dangerous quests, etc.).
DownloadRequest	requestDownloadSMS(java.lang.String playerName, java.lang.String password) Request a message with the download location for the client software.
DownloadRequest	requestDownloadSMSByHeader(java.lang.String playerName, java.lang.String password, java.lang.String header) Same as requestDownloadSMS(String, String) but also uses the given http header to guess the user's device.
DownloadRequest	requestDownloadSMSBySessionKey(java.lang.String sessionKey) Request a message with the download location for the client software.
void	requestPurchasedItem(java.lang.String sessionKey, java.lang.String appleProductId, java.lang.String transactionId, java.lang.String receipt) Counts the entities containing a specific entry in the memory db.
WebSession	resume(java.lang.String playerName, java.lang.String sessionKey) Password-less resume into existing session.
void	reward(java.lang.String sessionKey, java.lang.String player, int points) Reward the given Player with points.
boolean	setCode(java.lang.String key, long id, java.lang.String code) Applies a "download code" for the given entity.
void	setMemory(java.lang.String sessionKey, java.lang.String entityId, java.lang.String key, java.lang.String value) Add a key-value pair to a Entity's memory.
void	setMemoryForAll(java.lang.String sessionKey, java.lang.String key, java.lang.String value) Set a key-value pair to all the Entity's memory having the key.
void	setTradable(java.lang.String sessionKey, long entityId, boolean yes) Sets if a given entity is tradable.
Message	shout(java.lang.String sessionKey, java.lang.String receivingCell, java.lang.String message) Shout a text Message to a Cell.
void	showTicker(java.lang.String sessionKey, java.lang.String name, java.lang.String ticker) Shows a ticker message on the device of the given Player if logged in and if settings allow.
Event	speak(java.lang.String sessionKey, long gbangooId, java.lang.String message) Lets the given Gbangoo send the message to everyone in its current cell.
Event	speakTo(java.lang.String sessionKey, long gbangooId, java.lang.String player, java.lang.String message) Lets the given Gbangoo send a message to the specified player.
Gbangoo	stop(java.lang.String sessionKey, long gbangooId) Halts the given Gbangoo.
void	submitStatistics(java.lang.String sessionKey, java.lang.String data) This method is used to submit statistics for research purposes.
java.lang.String	subscribeToWebHook(java.lang.String sessionKey, int event, java.lang.String filter, java.lang.String url) Registers a Web Hook listener at the given URL for the given user.
int	takeOverCell(java.lang.String sessionKey, java.lang.String playerName, java.lang.String cellName, java.lang.String newOwner) Transfer the ownership of a cell to a new family
Trade	trade(java.lang.String sessionKey, java.lang.String partnerName, java.lang.String offeredGoodIdString, java.lang.String requestedGoodIdString) Add goods to the indicated offer.
int	transferInfrastructuresAndCells(java.lang.String sessionKey, java.lang.String playerName, java.lang.String newFamily) Transfer the infrstructures owned by a player from a family to another one
java.lang.String	unsubscribeFromWebHook(java.lang.String sessionKey, java.lang.String url) Unregisters a Web Hook listener at the given URL for the given user.
void	updateAvatar(java.lang.String sessionKey, long entityId, java.io.InputStream is) Updates the image of a given entity.
void	updateAvatarByRef(java.lang.String sessionKey, long entityId, long avatarId) Sets the image of a given entity by referencing an existing image.
void	updateDescription(java.lang.String sessionKey, long entityId, java.lang.String description) Sets the description field of the given entity.
void	updateEmail(java.lang.String sessionKey, java.lang.String playerName, java.lang.String email) Update the email of a Player.
void	updateGbangooType(java.lang.String sessionKey, long type, java.io.InputStream avatar, java.lang.String description, java.lang.String comment) Updates an existing Gbangoo type.
void	updateInfrastructureType(java.lang.String sessionKey, long type, java.io.InputStream avatar, java.lang.String description, java.lang.String comment) Updates an existing Infrastructure type.
Player	updateProfile(java.lang.String sessionKey, java.lang.String cellphone, java.lang.String email) Update the details of a Player.
void	updateProfileImage(java.lang.String sessionKey, java.io.InputStream image) Update the profile image of the authenticated Player.
void	updateResourceType(java.lang.String sessionKey, long type, java.lang.String screenname, java.io.InputStream avatar, java.lang.String description) Updates an existing Resource type.
Player	updateStatus(java.lang.String sessionKey, java.lang.String status) Updates the status message of a Player in a manner similar to a Twitter message, Facebook's status or a tagline in any instant messenger (eg, MSN and Skype).
Feature	whereAmI() Tries to locate the requester of this method with the help of HTTP header information, IP localization, etc.

Field Detail

ANDROID

static final short ANDROID

Android phone category.

See Also:

Constant Field Values

ANDROID_PLAT

static final short ANDROID_PLAT

Android platform.

See Also:

Constant Field Values

BADA

static final short BADA

bada platform.

See Also:

Constant Field Values

BLACKBERRY

static final short BLACKBERRY

BlackBerry phone category.

See Also:

Constant Field Values

BLACKBERRY_PLAT

static final short BLACKBERRY_PLAT

BlackBerry platform.

See Also:

Constant Field Values

BUG_SEVERITY_CRITICAL

static final int BUG_SEVERITY_CRITICAL

A critical bug.

See Also:

Constant Field Values

BUG_SEVERITY_ENHANCEMENT

static final int BUG_SEVERITY_ENHANCEMENT

Not a bug, but a possible enhancement.

See Also:

Constant Field Values

BUG_SEVERITY_MAJOR

static final int BUG_SEVERITY_MAJOR

A major bug.

See Also:

Constant Field Values

BUG_SEVERITY_MINOR

static final int BUG_SEVERITY_MINOR

A minor bug.

See Also:

Constant Field Values

BUG_SEVERITY_NORMAL

static final int BUG_SEVERITY_NORMAL

A medium bug.

See Also:

Constant Field Values

BUG_SEVERITY_TRIVIAL

static final int BUG_SEVERITY_TRIVIAL

A trivial bug.

See Also:

Constant Field Values

DEFAULT_EVENTS_AT_N

static final int DEFAULT_EVENTS_AT_N

The default number of local Events that are returned when calling getEventsAt(String).

See Also:

Constant Field Values

DEFAULT_FEATURED_STORIES_N

static final int DEFAULT_FEATURED_STORIES_N

The default number of featured Story objects that are requested with getFeaturedStories().

See Also:

Constant Field Values

DEFAULT_GLOBAL_EVENTS_N

static final int DEFAULT_GLOBAL_EVENTS_N

The number of events to list in a getGlobalEvents() call.

See Also:

Constant Field Values

DEFAULT_HIGHSCORE_FIRST

static final int DEFAULT_HIGHSCORE_FIRST

Parameter to indicate the rank of the first entry in the highscore.

See Also:

getHighscore(int, int, byte), Constant Field Values

DEFAULT_HIGHSCORE_N

static final int DEFAULT_HIGHSCORE_N

Parameter to indicate the number of entries in the highscore.

See Also:

getHighscore(int, int, byte), Constant Field Values

DEFAULT_HIGHSCORE_TYPE

static final byte DEFAULT_HIGHSCORE_TYPE

Default value for highscore type (is one of the following values: daily, weekly, monthly, annual or all times).

See Also:

getHighscore(int, int, byte), Constant Field Values

DEFAULT_MOST_POPULAR_N

static final int DEFAULT_MOST_POPULAR_N

The default number of the most popular Tags that are requested with getMostPopular().

See Also:

Constant Field Values

DEFAULT_NEWCOMERS_N

static final int DEFAULT_NEWCOMERS_N

The default number of newcomers that are requested with getNewcomers().

See Also:

Constant Field Values

DROP

static final byte DROP

Drop a Gbangoo.

See Also:

move(String, long, long), Constant Field Values

HIGHSCORE_TYPE_EVER

static final int HIGHSCORE_TYPE_EVER

Parameter to get the highscore of all times.

See Also:

getHighscore(int, int, byte), Constant Field Values

HIGHSCORE_TYPE_OFDAY

static final int HIGHSCORE_TYPE_OFDAY

Parameter to get the daily highscore.

See Also:

getHighscore(int, int, byte), Constant Field Values

HIGHSCORE_TYPE_OFMONTH

static final int HIGHSCORE_TYPE_OFMONTH

Parameter to get the monthly highscore.

See Also:

getHighscore(int, int, byte), Constant Field Values

HIGHSCORE_TYPE_OFWEEK

static final int HIGHSCORE_TYPE_OFWEEK

Parameter to get the weekly highscore.

See Also:

getHighscore(int, int, byte), Constant Field Values

HIGHSCORE_TYPE_OFYEAR

static final int HIGHSCORE_TYPE_OFYEAR

Parameter to get the annual highscore with.

See Also:

getHighscore(int, int, byte), Constant Field Values

IPHONE

static final short IPHONE

iPhone phone category.

See Also:

Constant Field Values

IPHONE_PLAT

static final short IPHONE_PLAT

iPhone platform.

See Also:

Constant Field Values

LIFT

static final byte LIFT

Lift a Gbangoo.

See Also:

move(String, long, long), Constant Field Values

MAEMO

static final short MAEMO

Maemo platform.

See Also:

Constant Field Values

MAX_EVENTS_AT_N

static final int MAX_EVENTS_AT_N

The maximum number of local Events that can be retrieved with getEventsAt(String, int).

See Also:

Constant Field Values

MAX_FEATURED_STORIES_N

static final int MAX_FEATURED_STORIES_N

The maximum number of featured Story objects that can be requested with getFeaturedStories(int).

See Also:

Constant Field Values

MAX_GLOBAL_EVENTS_N

static final int MAX_GLOBAL_EVENTS_N

Maximum value for event global requests. Use this in getGlobalEvents(int).

See Also:

getGlobalEvents(int), DEFAULT_GLOBAL_EVENTS_N, Constant Field Values

MAX_HIGHSCORE_N

static final int MAX_HIGHSCORE_N

Maximum value for highscore entry count. Use this in getHighscore(int, int, byte).

See Also:

getHighscore(int, int, byte), DEFAULT_HIGHSCORE_N, Constant Field Values

MAX_MESSAGES

static final int MAX_MESSAGES

This is the maximum number of messages returned by the methods getConversationWithGbangoo(String, long) and getConversationWithPlayer(String, String).

See Also:

getConversationWithGbangoo(String, long), getConversationWithPlayer(String, String), Constant Field Values

MAX_MESSAGES_N

static final int MAX_MESSAGES_N

The maximum number of messages returned by the API methods such as getShouts(String) and getStatusFeed(String).

See Also:

Constant Field Values

MAX_MOST_POPULAR_N

static final int MAX_MOST_POPULAR_N

The maximum number of the most popular Tags objects that can be requested with getMostPopular(int).

See Also:

Constant Field Values

MAX_NEWCOMERS_N

static final int MAX_NEWCOMERS_N

The maximum of newcomers that can be requested with getNewcomers(int).

See Also:

Constant Field Values

MOTOROLA

static final short MOTOROLA

Motorola phone category.

See Also:

Constant Field Values

MOTOROLA_PLAT

static final short MOTOROLA_PLAT

Motorola platform.

See Also:

Constant Field Values

NOKIA

static final short NOKIA

Nokia phone category.

See Also:

Constant Field Values

OPEN_MOKO

static final short OPEN_MOKO

Open Moko platform.

See Also:

Constant Field Values

OTHER

static final short OTHER

Other phone category.

See Also:

Constant Field Values

PIECE_AT_RANDOM_TILE

static final int PIECE_AT_RANDOM_TILE

Specifies to piece a Tag to a random tile within the current Cell of the logged in Player (this is standard behaviour on clients).

See Also:

piece(String, long, long), Constant Field Values

PIECE_AWAY

static final int PIECE_AWAY

Specifies to piece a Tag to nowhere in order to dispose it from the current Pocket.

See Also:

piece(String, long, long), Constant Field Values

SAMSUNG

static final short SAMSUNG

Samsung phone category.

See Also:

Constant Field Values

SONYERICSSON

static final short SONYERICSSON

Sony Ericsson phone category.

See Also:

Constant Field Values

SONYERICSSON_PLAT

static final short SONYERICSSON_PLAT

Sony Ericsson platform.

See Also:

Constant Field Values

SYMBIAN_S60

static final short SYMBIAN_S60

Symbian S60 platform.

See Also:

Constant Field Values

UIQ

static final short UIQ

UIQ platform.

See Also:

Constant Field Values

UNKNOWN

static final short UNKNOWN

The phone model was not listed so the platform is unknown.

In this case the user should be contacted to include his phone model in the list.

See Also:

Constant Field Values

UNSUPPORTED

static final short UNSUPPORTED

Unsupported platform.

See Also:

Constant Field Values

VERSION

static final int VERSION

The major version number of this API.

See Also:

Constant Field Values

WINDOWS_MOBILE

static final short WINDOWS_MOBILE

Windows Mobile phone category.

See Also:

Constant Field Values

WINDOWS_MOBILE_PLAT

static final short WINDOWS_MOBILE_PLAT

Windows Mobile platform.

See Also:

Constant Field Values

Method Detail

abort

Trade abort(java.lang.String sessionKey,
            long tradeId)
            throws APIException

Decline an incoming trade offer.

Parameters:

sessionKey - the session key of the authenticated user

tradeId - the offer to be declined

Returns:

the declined offer

Throws:

APIException - fails if the session key is wrong,
or, if the trade id is unknown

accept

Trade accept(java.lang.String sessionKey,
             long tradeId)
             throws APIException

Accept an incoming trade offer.

Parameters:

sessionKey - the session key of the authenticated user

tradeId - the offer to be accepted

Returns:

the accepted offer

Throws:

APIException - fails if the session key is wrong,
or, if the trade id is unknown

acceptFriendship

Player acceptFriendship(java.lang.String sessionKey,
                        java.lang.String player)
                        throws APIException

Accepts the friendship offer of another player.

Parameters:

sessionKey - the session key of the authenticated user

player - the player who offered his friendship

Returns:

the reference to the player who offered his friendship and is now a friend

Throws:

APIException - fails if the session key is wrong,
or, if the player is unknown
or, if there is no friendship offer by the specified player

addToOffer

Trade addToOffer(java.lang.String sessionKey,
                 long tradeId,
                 long offeredGoodId,
                 long requestedGoodId)
                 throws APIException

Add goods to the indicated offer.

Parameters:

sessionKey - the session key of the authenticated user

tradeId - the current trade/offer

offeredGoodId - an id of a good that is offered (may be 0, if nothing to offer)

requestedGoodId - an id of a good that is requested (may be 0, if nothing is requested)

Returns:

the updated referring trading object

Throws:

APIException - fails if the session key is wrong,
or, if the trade id is unknown,
or, the offered good id is unknown,
or, the requested good id is unknown

adjustInterests

Player adjustInterests(java.lang.String sessionKey,
                       boolean play,
                       boolean collecting,
                       boolean trading,
                       boolean events,
                       boolean networking,
                       boolean travel,
                       boolean dating)
                       throws APIException

Update your keywords of interest.

Parameters:

sessionKey - the session key of the authenticated user

play - true if you want to play in general (quests, etc.)

collecting - true if you are interested in collecting for puzzles

trading - true if you are interested in trading goods

events - true if you are interested in local events

networking - true if you are interested in chatting up new peers in your neighbourhood

travel - true if you are interested in travelling tipps on site

dating - true if you are interested

Returns:

the updated player information

Throws:

APIException - if the session key does not exist

beamGbangoo

Gbangoo beamGbangoo(java.lang.String sessionKey,
                    long gbangooId,
                    java.lang.String cellName)
                    throws APIException

Teleport a Gbangoo to a given cell.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the id of the Gbangoo that sould be teleported

cellName - the id of the destination cell

Returns:

the updated Gbangoo object

Throws:

APIException - fails if the session key is wrong,
or, if the Gbangoo is not owned by the authenticated player
or, if the id of the destination cell is unknown

beamInfrastructure

Infrastructure beamInfrastructure(java.lang.String sessionKey,
                                  long infrastructureId,
                                  java.lang.String cellName)
                                  throws APIException

Teleport an infrastructure to a given cell.

Parameters:

sessionKey - the session key of the authenticated user

infrastructureId - the id of the infrastructure that sould be teleported

cellName - the id of the destination cell

Returns:

the updated Infrastructure object

Throws:

APIException - fails if the session key is wrong,
or, if the infrastructure is not owned by the authenticated player
or, if the id of the destination cell is unknown

beamResource

Resource beamResource(java.lang.String sessionKey,
                      long resourceId,
                      java.lang.String cellName)
                      throws APIException

Teleport a resource to a given cell.

Parameters:

sessionKey - the session key of the authenticated user

resourceId - the id of the resource that sould be teleported

cellName - the id of the destination cell

Returns:

the updated Resource object

Throws:

APIException - fails if the session key is wrong,
or, if the resource is not owned by the authenticated player
or, if the id of the destination cell is unknown

breakWith

Player breakWith(java.lang.String sessionKey,
                 java.lang.String player,
                 java.lang.String lastMessage)
                 throws APIException

Break with a prior friend and, optionally, let him know why.

Parameters:

sessionKey - the session key of the authenticated user

player - the prior friend

lastMessage - the good-bye message

Returns:

the updated player information (including the updated friends list)

Throws:

APIException - if the session key does not exist

broadcast

void broadcast(java.lang.String sessionKey,
               java.lang.String message)
               throws APIException

Sends a Message to all player friends.

Parameters:

sessionKey - the session key of the authenticated Player

message - the content of the message

Throws:

APIException - if the given session key is invalid, or
the message content is inappropriate

build

Infrastructure build(java.lang.String sessionKey,
                     long gbangooId,
                     long type,
                     java.lang.String screenname)
                     throws APIException

A Gbangoo starts with a construction of a building of given type at its current location.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the id of the Gbangoo that should start with the construction

type - the type of building to be built

screenname - the name to be given to the building

Returns:

the updated Gbangoo object

Throws:

APIException - fails if the session key is wrong,
or, if the Gbangoo is not owned by the authenticated player,
or, if the Gbangoo cannot build (eg. busy, in inventory, tile not available),
or, if the Gbangoo does not know the type, yet,
or, if there is insufficient material to build the type indicated,

challenge

Challenge challenge(java.lang.String sessionKey,
                    long challengerId,
                    long opponentId)
                    throws APIException

Start a match between the initiating challenger and the challenged opponent.

Parameters:

sessionKey - the session key of the authenticated user

challengerId - the initiating Gbangoo

opponentId - the challenged Gbangoo

Returns:

an referring object containing information about the ongoing match

Throws:

APIException - fails if the session key is wrong,
or if a Gbangoo with the given id does not exist,
or if the initiating Gbangoo is not owned by the authenticated player

changeSettings

Player changeSettings(java.lang.String sessionKey,
                      boolean friendCanSeeMyPosition,
                      boolean everybodyCanSeeMyPosition,
                      boolean notifyBySMS,
                      boolean notifyByEmail)
                      throws APIException

Update your privacy sensitive settings.

Parameters:

sessionKey - the session key of the authenticated user

friendCanSeeMyPosition - true if your friends should be able to see your last position within the game (cell-precision, only)

everybodyCanSeeMyPosition - true if all players should be able to see your last position within the game (cell-precision, only)

notifyBySMS - true if you want to receive notifications to your cell phone number indicated in your profile

notifyByEmail - true if you want to receive notifications to your email address indicated in your profile

Returns:

the updated player information

Throws:

APIException - if the session key does not exist

clear

Tile clear(java.lang.String sessionKey,
           long tileId)
           throws APIException

Remove the indicated tile from the Gbanga world.

Parameters:

sessionKey - the session key of the authenticated user

tileId - the id of the tile to remove

Returns:

information about the removed tile

Throws:

APIException - if the session key does not exist, or
the tile does not exist

collectResource

void collectResource(java.lang.String sessionKey,
                     long id)
                     throws APIException

Collects a resource.

Parameters:

sessionKey - the key of the session of the Player who created the product item

id - the id of the resource

Throws:

APIException - If the session key is invalid or the id doesn't correspond to a resource

createAvatar

long createAvatar(java.lang.String sessionKey,
                  java.io.InputStream image)
                  throws APIException

Creates a new avatar from the given InputStream.

Parameters:

sessionKey - the session key of the authenticated Player

image - the image to create an avatar from

Returns:

the avatar ID

Throws:

APIException - if the session key is invalid, or
the avatar binary is corrupt

createDescription

long createDescription(java.lang.String sessionKey,
                       java.lang.String text)
                       throws APIException

Creates a new description from the given text.

Parameters:

sessionKey - the session key of the authenticated Player

text - the String to create a description from

Returns:

the description ID

Throws:

APIException - if the session key is invalid, or
the description is inappropriate

createGbangoo

Gbangoo createGbangoo(java.lang.String sessionKey,
                      long type,
                      java.lang.String name,
                      long avatar,
                      long description)
                      throws APIException

Creates a Gbangoo. It will belong to the authenticated Player.

Parameters:

sessionKey - the session key of the authenticated Player

type - the Gbangoo's type

name - the screen name of the Gbangoo

avatar - the optional avatar ID

description - the optional description ID

Returns:

the Gbangoo created

Throws:

APIException - if the session key is invalid, or
the screenname is inappropriate, or
the avatar binary is corrupt

createGbangooType

long createGbangooType(java.lang.String sessionKey,
                       java.io.InputStream avatar,
                       java.lang.String description,
                       java.lang.String comment)
                       throws APIException

Creates a new Gbangoo type. The type encompasses an avatar image and a description. The new type will be assigned a numerical id uniquely identifying it.

Parameters:

sessionKey - the session key of the authenticated Player

avatar - the avatar image displayed for Gbangoos of the new type

description - the description displayed for Gbangoos of the new type

comment - an optional comment describing the purpose of the new type

Returns:

the numerical id uniquely identifying the new type

Throws:

APIException - if the session key is invalid, or
the description is inappropriate, or
the avatar binary is corrupt

createGube

Gube createGube(java.lang.String sessionKey,
                long tileId,
                int lifetime,
                int color)
                throws APIException

Pulls a Gube at the given location.

Parameters:

sessionKey - the session key of the authenticated Player

tileId - the location where the Gube should be placed

lifetime - the number of ticks the Gube should remain

color - the colour the Gube should have

Returns:

the Gube created

Throws:

APIException - if the session key is invalid, or
the location is unknown, or
the life time is out of bounds, or
the colour is invalid

createInfrastructure

Infrastructure createInfrastructure(java.lang.String sessionKey,
                                    long type,
                                    java.lang.String name,
                                    long avatar,
                                    long description)
                                    throws APIException

Creates an Infrastructure. It will belong to the authenticated Player. If no avatar image is specified, the default image for the given type will be used.

Parameters:

sessionKey - the session key of the authenticated Player

type - the type of the infrastructure

name - the screen name of the Infrastructure

avatar - the optional avatar ID

description - the optional description ID

Returns:

the Infrastructure created

Throws:

APIException - if the session key is invalid, or
the screenname is inappropriate, or
the type is inappropriate, or
the avatar binary is corrupt

createInfrastructureType

long createInfrastructureType(java.lang.String sessionKey,
                              java.io.InputStream avatar,
                              java.lang.String description,
                              java.lang.String comment)
                              throws APIException

Creates a new Infrastructure type. The type encompasses an avatar image and a description. The new type will be assigned a numerical id uniquely identifying it.

Parameters:

sessionKey - the session key of the authenticated Player

avatar - the avatar image displayed for infrastructures of the new type

description - the description displayed for infrastructures of the new type

comment - an optional comment describing the purpose of the new type

Returns:

the numerical id uniquely identifying the new type

Throws:

APIException - if the session key is invalid, or
the description is inappropriate, or
the avatar binary is corrupt

createResource

Resource createResource(java.lang.String sessionKey,
                        long type,
                        short amount)
                        throws APIException

Creates a particular amount of a resource of given type.

Parameters:

sessionKey - the session key of the authenticated Player

type - the type of the resource to be created

amount - the amount

Returns:

the Resource created

Throws:

APIException - if the session key is invalid, or
the the resource type is invalid

createResourceType

long createResourceType(java.lang.String sessionKey,
                        java.lang.String screenname,
                        java.io.InputStream avatar,
                        java.lang.String description)
                        throws APIException

Creates a new Resource type. The type encompasses a screen name, an avatar image and a description. The new type will be assigned a numerical id uniquely identifying it.

Parameters:

sessionKey - the session key of the authenticated Player

screenname - the screen name displayed for resources of the new type

avatar - the avatar image displayed for resources of the new type

description - the description displayed for resources of the new type

Returns:

the numerical id uniquely identifying the new type

Throws:

APIException - if the session key is invalid, or
the screen name or description is inappropriate, or
the avatar binary is corrupt

createTag

Tag createTag(java.lang.String sessionKey,
              long content,
              long avatar)
              throws APIException

Parameters:

sessionKey - the session key of the authenticated Player

content - the content ID

avatar - the avatar ID

Returns:

the Tag created

Throws:

APIException - if the session key is invalid, or
the content is inappropriate, or
the avatar binary is corrupt

decorate

Cell decorate(java.lang.String sessionKey,
              long cellId,
              int[] flag)
              throws APIException

Set the flag for a given cell.

Parameters:

sessionKey - the session key of the authenticated user

cellId - the id of the cell with a new flat

flag - the dots of the new flag

Returns:

the updated cell object

Throws:

APIException - fails if the session key is wrong,
or, if the cell was not discovered by the authenticated player
or, if the id of the cell is unknown
or, if the flag is unknown

discover

Feature discover(java.lang.String sessionKey,
                 java.lang.String cellName,
                 float latitude,
                 float longitude,
                 java.lang.String cellFlagString)
                 throws APIException

Creates a new cell based on the the geographical location of a given player.

Parameters:

sessionKey - the session key of the authenticated user

cellName - the name of the new cell

latitude - the latitude

longitude - the longitude

cellFlagString - the flag encoded as a string of comma separated integers

Returns:

the cell if was already discovered

Throws:

APIException - fails if the session key is wrong,

dispose

void dispose(java.lang.String sessionKey,
             long goodId)
             throws APIException

Disposes of the given Good. Only the creator of a good (but not the owner) can dispose of it. If the requester is not the creator, the good won't be disposed of, but no APIException will be thrown.

Parameters:

sessionKey - the key of the session of the Player who created the entity

goodId - the id of the good which should be disposed of

Throws:

APIException - if the session key is invalid,
the id of the good is unknown

findOnMap

FeatureCollection findOnMap(java.lang.String queryPhrase)
                            throws APIException

Locates the given phrase in Gbanga (Cell name, city name, ZIP code, etc.)

Parameters:

queryPhrase - a freeform text that describes a geo location or a game entity

Returns:

a list of Placemarks that might be a hit

Throws:

APIException - if the query was empty or the query phrase invalid in another manner

forceFriendship

Player forceFriendship(java.lang.String sessionKey,
                       java.lang.String offerer,
                       java.lang.String receiver)
                       throws APIException

Forces a friendship offer to be sent from one player to another one.

Parameters:

sessionKey - the session key of the authenticated user

offerer - the player forced to send a friendship offer

receiver - the receiver of the friendship offer

Returns:

the reference to the player that was forced to offer friendship

Throws:

APIException - fails if the session key is wrong,
or, if either the offerer or receiver is unknown

free

void free(java.lang.String sessionKey,
          long entityId)
          throws APIException

Releases the given entity to be freely available to other Players.

NOTE: the entity must not be in the player's pocket when calling this method.

Parameters:

sessionKey - the key of the session of the owning Player

entityId - the id of the entity which should be released

Throws:

APIException - if the session key is invalid, the entity id unknown

getAllMessages

Message[] getAllMessages(java.lang.String sessionKey)
                         throws APIException

Returns a list with Messages that have not been read by the recieving Player yet.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

a list with unread Messages

Throws:

APIException - if the given session key is invalid

getCell

Cell getCell(java.lang.String cellName)
             throws APIException

Retrieves the cell with the given name.

Parameters:

cellName - the unique cell name

Returns:

the details about the cell

Throws:

APIException - thrown if cell name does not exist

getCellNames

java.lang.String[] getCellNames(float topLatitude,
                                float leftLongitude,
                                float bottomLatitude,
                                float rightLongitude)
                                throws APIException

Retrieves the names of all cells within the specified area. The area is specified given the coordinates of a north-western point (top latitude, left longitude) and coordinates of a south-eastern point (bottom latitude, right longitude).

Parameters:

topLatitude - the north-west point's latitude

leftLongitude - the north-west point's longitude

bottomLatitude - the south-east point's latitude

rightLongitude - the south-east point's longitude

Returns:

the names of all cells within the specified area

Throws:

APIException - if the specified area is invalid

getConversationWithGbangoo

Message[] getConversationWithGbangoo(java.lang.String sessionKey,
                                     long gbangoo)
                                     throws APIException

Returns the last messages between you and a Gbangoo (max. 5 messages)

Parameters:

sessionKey - the key of the session to check

gbangoo - the id of the Gbangoo you have chatted with

Returns:

an array with the Messages

Throws:

APIException - if the session key is invalid, or
no Gbangoo with the indicated id exists

getConversationWithPlayer

Message[] getConversationWithPlayer(java.lang.String sessionKey,
                                    java.lang.String player)
                                    throws APIException

Returns the last messages between two players (max. MAX_MESSAGES messages)

Parameters:

sessionKey - the key of the session to check

player - the player one has chatted with

Returns:

an array with the Messages

Throws:

APIException - if the session key is invalid, or
the indicated player name does not exist

getCountEntitiesWithMemory

int getCountEntitiesWithMemory(java.lang.String sessionKey,
                               java.lang.String key,
                               java.lang.String value)
                               throws APIException

Counts the entities containing a specific entry in the memory db.

Parameters:

sessionKey - the temporarily valid key of a player's session

key - the memory key

value - the value to filter with

Returns:

the number of entities containing the key and value specified

Throws:

APIException

getDownloadLink

java.lang.String getDownloadLink(java.lang.String sessionKey)
                                 throws APIException

Requests a message with the download location for the client software.

Parameters:

sessionKey -

Returns:

a well-formed URL (incl. http://)

Throws:

APIException - if the service is currently not available or the session key is invalid.

getEntitiesWithMemory

EntitiesFromMemory getEntitiesWithMemory(java.lang.String sessionKey,
                                         java.lang.String memkey,
                                         java.lang.String value)
                                         throws APIException

Gets the entities containing a specific entry in the memory db.

Parameters:

sessionKey - the temporarily valid key of a player's session

memkey - the memory key

value - the value to filter with.

Returns:

the entities containing the key and value specified.

Throws:

APIException

getEventsAt

Event[] getEventsAt(java.lang.String cellname)
                    throws APIException

Assorts a list with local Events at a given Cell.

Parameters:

cellname - the name of a Cell.

Returns:

a list with local Events

Throws:

APIException - if the given cell is unknown

See Also:

DEFAULT_EVENTS_AT_N

getEventsAt

Event[] getEventsAt(java.lang.String cellname,
                    int n)
                    throws APIException

Assorts a list with a given number of local Events at a given Cell.

Parameters:

cellname - the name of a Cell.

n - the number of Events to be returned

Returns:

a list with local Events

Throws:

APIException - if the given cell is unknown

See Also:

DEFAULT_EVENTS_AT_N, MAX_EVENTS_AT_N

getFeaturedStories

Story[] getFeaturedStories()

Returns a list of featured stories interesting to be displayed on the frontpage.

Returns:

a list with Story objects.

See Also:

getFeaturedStories(int), DEFAULT_FEATURED_STORIES_N

getFeaturedStories

Story[] getFeaturedStories(int n)
                           throws APIException

Returns a list of featured stories interesting to be displayed on the frontpage.

Parameters:

n - the number of Story objects to be returned.

Returns:

a list with Story objects.

Throws:

APIException - if the indicated number was too high or less than 1

See Also:

MAX_FEATURED_STORIES_N, DEFAULT_FEATURED_STORIES_N

getFriends

Player[] getFriends(java.lang.String sessionKey)
                    throws APIException

Returns a list with friend Players of a given authenticated Player.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

a list with friend Players

Throws:

APIException - if the given session key is invalid

getFriendsInDetail

Player[] getFriendsInDetail(java.lang.String sessionKey)
                            throws APIException

Returns a list with friend Players containing the location if allowed of a given authenticated Player.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

a list with friend Players

Throws:

APIException - if the given session key is invalid

getGbangoo

Gbangoo getGbangoo(java.lang.String gbangooName,
                   java.lang.String ownerName)
                   throws APIException

Retrieve a Gbangoo owned by the indicated player.

Parameters:

gbangooName - the name of the Gbangoo

ownerName - the owning player

Returns:

the Gbagnoo details

Throws:

APIException - thrown if one or both names do not exist

getGbangooById

Gbangoo getGbangooById(long gbangooId)
                       throws APIException

Retrieve a Gbangoo given its ID.

Parameters:

gbangooId - the ID the Gbangoo

Returns:

the Gbagnoo details

Throws:

APIException - thrown if there is no Gbangoo with the given ID

getGbangooById

Gbangoo getGbangooById(java.lang.String sessionKey,
                       long gbangooId,
                       java.lang.String lang)
                       throws APIException

Retrieve a Gbangoo given its ID containing the description in the player's language.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the ID the Gbangoo

lang - if this is set, will override player's settings

Returns:

the Gbagnoo details

Throws:

APIException - thrown if there is no Gbangoo with the given ID

getGlobalEvents

Event[] getGlobalEvents()

Returns a number of events that take place right now.

Returns:

a list with Storys, Challenges, Conversations, Trades and Visits

See Also:

DEFAULT_GLOBAL_EVENTS_N

getGlobalEvents

Event[] getGlobalEvents(int n)
                        throws APIException

Returns a number of events that take place right now.

Parameters:

n - the number of events to return

Returns:

a list with Storys, Challenges, Conversations, Trades and Visits

Throws:

APIException - if the number of events argument was out of bounds (less than 1 or greater than the maximum)

See Also:

DEFAULT_GLOBAL_EVENTS_N, MAX_GLOBAL_EVENTS_N

getHighscore

Player[] getHighscore(int first,
                      int n,
                      byte type)
                      throws APIException

Assorts a list with entries for the given type of highscore with the given number of entries with a given rank.

 Rank            Entry
 --------------------------------
 [first]         Player details
 [first + 1]     Player details
 [first + 2]     Player details
    ...                ...
 [first + n - 1] Player details
 

Parameters:

first - the rank of the first entry

n - number of entries to return

type - the type of highscore (daily, weekly, monthly, annual or all times)

Returns:

a list with player objects

Throws:

APIException - if the rank and/or the number of entries is out of bounds (eg. too high or less than zero) if the type is unknown

See Also:

HIGHSCORE_TYPE_EVER, HIGHSCORE_TYPE_OFDAY, HIGHSCORE_TYPE_OFWEEK, HIGHSCORE_TYPE_OFMONTH, HIGHSCORE_TYPE_OFYEAR

getInfrastructure

Infrastructure getInfrastructure(long infrastructureId)
                                 throws APIException

Retrieve an Infrastructure given its ID.

Parameters:

infrastructureId - the ID of the Infrastructure

Returns:

the Infrastructure details

Throws:

APIException - thrown if there is no Infrastructure with the given ID

getInfrastructure

Infrastructure getInfrastructure(java.lang.String sessionKey,
                                 long infrastructureId,
                                 java.lang.String lang)
                                 throws APIException

Retrieve an Infrastructure given its ID containing the description in the player's language.

Parameters:

sessionKey - the session key of the authenticated user

infrastructureId - the ID of the Infrastructure

lang - if this is set, will override player's settings

Returns:

the Infrastructure details

Throws:

APIException - thrown if there is no Infrastructure with the given ID

getLoginType

int getLoginType(java.lang.String playerName)
                 throws APIException

Request a membership for the given person with the given details.

Parameters:

playerName - the username of the player

Returns:

a in representing the login type

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

getMapTile

FeatureCollection getMapTile(float topLatitude,
                             float leftLongitude,
                             float bottomLatitude,
                             float rightLongitude)
                             throws APIException

Returns a list of placemarks that are within the specified area.

This map is dynamically created and projected to the given size of the plane.

Parameters:

topLatitude - top latitude

leftLongitude - left longitude

bottomLatitude - bottom latitude

rightLongitude - right longitude

Returns:

a collection with Features

Throws:

APIException - if projection size is invalid (eg. negative or too big) or coordinates are invalid.

getMemory

java.lang.String getMemory(java.lang.String sessionKey,
                           java.lang.String entityId,
                           java.lang.String key)
                           throws APIException

Return the value of a given key in a given Entity's memory.

Parameters:

sessionKey - the session key of the authenticated Player

entityId - the id/name of the Entity which memory should be queried

key - the key to get the value from

Returns:

the value to that key

Throws:

APIException - if the session key is invalid, or
the Entity id is unknown, or
the key is invalid

getMostPopular

Tag[] getMostPopular()

Returns a list with the most popular Tags.

Returns:

a list of the most popular Tags

See Also:

DEFAULT_MOST_POPULAR_N

getMostPopular

Tag[] getMostPopular(int n)
                     throws APIException

Returns a gien number of the most popular Tags.

Parameters:

n - the number of Tags to be returned

Returns:

a list of the most popular Tags

Throws:

APIException - if the indicated number was out of bounds

See Also:

MAX_MOST_POPULAR_N, DEFAULT_MOST_POPULAR_N

getNewcomers

Player[] getNewcomers()

Assorts a list with Players that have recently signed up. The data is potentially anonymized.

Returns:

a list with players that have recently signed up Gbanga.

See Also:

DEFAULT_NEWCOMERS_N, getNewcomers(int)

getNewcomers

Player[] getNewcomers(int n)
                      throws APIException

Assorts a list with Players that have recently signed up. The data is potentially anonymized.

Parameters:

n - the number of Players to be returned.

Returns:

a list with Players that have recently signed up Gbanga.

Throws:

APIException - if the indicated number of Players was too high or less than 1

See Also:

MAX_NEWCOMERS_N, DEFAULT_NEWCOMERS_N

getNumCells

int getNumCells(float topLatitude,
                float leftLongitude,
                float bottomLatitude,
                float rightLongitude)
                throws APIException

Gets the number of cells within the specified area. The area is specified given the coordinates of a north-western point (top latitude, left longitude) and coordinates of a south-eastern point (bottom latitude, right longitude).

Parameters:

topLatitude - the north-west point's latitude

leftLongitude - the north-west point's longitude

bottomLatitude - the south-east point's latitude

rightLongitude - the south-east point's longitude

Returns:

the number of cells within the specified area

Throws:

APIException - if the specified area is invalid

getPlayer

Player getPlayer(java.lang.String playerName)
                 throws APIException

Retrieve a player indicated the player name.

Parameters:

playerName - the name of the player

Returns:

the details about the player

Throws:

APIException - thrown if player name does not exist

getPlayer

Player getPlayer(java.lang.String sessionKey,
                 java.lang.String playerName)
                 throws APIException

Retrieve a player indicated the player name and extra details if the caller is a friend.

Parameters:

sessionKey - the session key of the caller

playerName - the name of the player

Returns:

the details about the player

Throws:

APIException - thrown if player name does not exist or invalid session key

getPlayersIn

FeatureCollection getPlayersIn(float topLatitude,
                               float leftLongitude,
                               float bottomLatitude,
                               float rightLongitude)
                               throws APIException

Returns a list of players that are present within the specified area.

Parameters:

topLatitude - top latitude

leftLongitude - left longitude

bottomLatitude - bottom latitude

rightLongitude - right longitude

Returns:

a collection with Features

Throws:

APIException - if projection size is invalid (eg. negative or too big) or coordinates are invalid.

getPlayersIn

FeatureCollection getPlayersIn(java.lang.String sessionKey,
                               float topLatitude,
                               float leftLongitude,
                               float bottomLatitude,
                               float rightLongitude)
                               throws APIException

Returns a list of players that are present within the specified area. This also includes the friends that reveal their position only to their friends.

Parameters:

sessionKey - the session key of the authenticated user

topLatitude - top latitude

leftLongitude - left longitude

bottomLatitude - bottom latitude

rightLongitude - right longitude

Returns:

a collection with Features

Throws:

APIException - if projection size is invalid (eg. negative or too big) or coordinates are invalid.

See Also:

getPlayersIn(float, float, float, float)

getPocket

Pocket getPocket(java.lang.String sessionKey)
                 throws APIException

Returns the personal pocket.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

information about that pocket

Throws:

APIException - if the session key does not exist

getPocketOf

Pocket getPocketOf(java.lang.String sessionKey,
                   java.lang.String playerName)
                   throws APIException

Returns the pocket of the given player.

Parameters:

sessionKey - the session key of the authenticated user

playerName - the name of the player whose pocket to get

Returns:

information about the given player's pocket

Throws:

APIException - if the session key does not exist, or
if the given player does not exist

getPromotion

java.lang.String getPromotion()

Returns HTML and Javascript code with a currently promoted subject.

Returns:

HTML and Javascript code

getRandomCell

Cell getRandomCell(float topLatitude,
                   float leftLongitude,
                   float bottomLatitude,
                   float rightLongitude)
                   throws APIException

Retrieves a random cell within the specified area. The area is specified given the coordinates of a north-western point (top latitude, left longitude) and coordinates of a south-eastern point (bottom latitude, right longitude).

Parameters:

topLatitude - the north-west point's latitude

leftLongitude - the north-west point's longitude

bottomLatitude - the south-east point's latitude

rightLongitude - the south-east point's longitude

Returns:

a random cell within the specified area

Throws:

APIException - if the specified area is invalid
or if the specified area does not contain any cells

getRanking

java.lang.String[] getRanking(java.lang.String memkey,
                              int from,
                              int count)
                              throws APIException

Gets the ranking of players according to the natural ordering of values in the players' memory for a given key and rank range.

The ranking should only be used on memory entries where the values are comparable against each other, and an order can be established.

Parameters:

memkey - the memory

from - the rank to start with

count - the number of players to return starting from the specified rank

Returns:

the names of the players in the rank range

Throws:

APIException

getResource

Resource getResource(long id)
                     throws APIException

Retrieve a resource given the id.

Parameters:

id - the id of the resource

Returns:

the details about the resource

Throws:

APIException - thrown if id does not exist

getResource

Resource getResource(java.lang.String sessionKey,
                     long id,
                     java.lang.String lang)
                     throws APIException

Retrieve a resource given the id containing the description in the player's language..

Parameters:

sessionKey - the session key of the authenticated user

id - the id of the resource

lang - if this is set, will override player's settings

Returns:

the details about the resource

Throws:

APIException - thrown if id does not exist

getShouts

Message[] getShouts(java.lang.String sessionKey)
                    throws APIException

Gets the most recent shouts.

Parameters:

sessionKey - the session key of the Player

Returns:

the most recent shouts

Throws:

APIException - if the session key is invalid

getStatusFeed

Message[] getStatusFeed(java.lang.String sessionKey)
                        throws APIException

Gets the status feed messages.

Parameters:

sessionKey - the session key of the Player

Returns:

the status feed messages

Throws:

APIException - if the session key is invalid

getTag

Tag getTag(long id)
           throws APIException

Retrieve a tag given the id.

Parameters:

id - the id of the tag

Returns:

the details about the tag

Throws:

APIException - thrown if id does not exist

getUnreadMessages

Message[] getUnreadMessages(java.lang.String sessionKey)
                            throws APIException

Returns a list with Messages that have not been read by the recieving Player yet.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

a list with unread Messages

Throws:

APIException - if the given session key is invalid

getVersion

java.lang.String getVersion()

Returns a canonical version String including assembly information and server time.

Returns:

a String of variable length including both chars and digits

getWebHookSubscriptions

WebHookSubscription[] getWebHookSubscriptions(java.lang.String sessionKey)
                                              throws APIException

Gets all subscriptions to any Web Hook for the given user.

Parameters:

sessionKey - the key of the session for which to get the subscriptions

Returns:

all subscriptions to any Web Hook for the given user

Throws:

APIException - if the session key is invalid, or the retrieval of subscriptions failed due to some other reason

getYourEvents

Event[] getYourEvents(java.lang.String sessionKey)
                      throws APIException

Returns a number of events that are relevant to an authenticated player personally.

Parameters:

sessionKey - the session key of the authenticated user

Returns:

a list with Storys, Challenges, Conversations, Trades and Visits

Throws:

APIException - if the session key is invalid

getYourEvents

Event[] getYourEvents(java.lang.String sessionKey,
                      int n)
                      throws APIException

Returns a number of events that are relevant to an authenticated player personally.

Parameters:

sessionKey - the session key of the authenticated user

n - the number of events to return

Returns:

a list with Storys, Challenges, Conversations, Trades and Visits

Throws:

APIException - if the session key is invalid, or
if the number of events argument was out of bounds (less than 1 or greater than the maximum)

give

Good give(java.lang.String sessionKey,
          java.lang.String receivingPlayer,
          long goodId)
          throws APIException

Transfers the given Good from one Pocket to another Players Pocket.

Parameters:

sessionKey - the session key of the authenticated Player

receivingPlayer - the username of the receiving Player

goodId - the id of the Good to trade

Returns:

the updated Good with new owner

Throws:

APIException - if the session key is invalid, or
the Player is unknown, or
there is no Good with the given id

interact

void interact(java.lang.String sessionKey,
              long id)
              throws APIException

Interact with an infrastructure.

Parameters:

sessionKey - the key of the session of the Player who created the product item

id - the id of the infrastructure to interact with

Throws:

APIException - If the session key is invalid or the id doesn't correspond to an infrastructure

invite

boolean invite(java.lang.String sessionKey,
               java.lang.String name,
               java.lang.String contactInfo)
               throws APIException

Send an invitation to the given contact. After registration, an initial friendship between the player of the session and the invitee will be established automatically.

Parameters:

sessionKey - the session key of the inviting player

name - the name of the invitee

contactInfo - the contact info that is a phone number, or an email, or a postal address

Returns:

true if the invitation could be delivered (this is true for postal addresses, if one can geo-reference it. It does not guarantee that it could be delivered or the recipient exists)

Throws:

APIException - if the session key is unknown, or
the name was empty, or
the contact info could not be mined

isAvailable

boolean isAvailable(java.lang.String name)

Checks if the given name is available.

Parameters:

name - a suggested name

Returns:

true if the name is not taken

isEmailAvailable

boolean isEmailAvailable(java.lang.String email)
                         throws APIException

Checks if the given email address is available.

Parameters:

email - an email address

Returns:

true if the email address is valid and not taken

Throws:

APIException - if the given email address is invalid

isFBUidGbangaUsr

java.lang.String isFBUidGbangaUsr(long fbuid,
                                  java.lang.String fBsessionKey)

Checks if the given name is available.

Parameters:

fbuid - Facebook UersID

fBsessionKey - Facebook Session that authentificates this user

Returns:

GbangaUsername if the facebook user is registered in Gbanga

isPhoneAvailable

boolean isPhoneAvailable(java.lang.String phone)
                         throws APIException

Checks if the given (cell) phone number address is available.

Parameters:

phone - an (cell) phone number

Returns:

true if the (cell) phone number is valid and not taken

Throws:

APIException - if the given cell phone number is invalid

isTimedOut

boolean isTimedOut(java.lang.String sessionKey)

Checks whether a given session is timed-out.

Parameters:

sessionKey - the key of the session to check

Returns:

true, if the session is timed-out

isTradable

boolean isTradable(long entityId)
                   throws APIException

Checks if a given entity is tradable.

Parameters:

entityId - the id of the entity to check if it is tradable

Returns:

true if one can trade it

Throws:

APIException - if the entity id is unknown

isUDIDGbangaUsr

java.lang.String isUDIDGbangaUsr(java.lang.String udid)

Checks if the given name is available.

Parameters:

udid - UDID of an iPhone the user currently plays on

Returns:

GbangaUsername if the facebook user is registered in Gbanga

jump

Gube jump(java.lang.String sessionKey,
          long gbangooId)
          throws APIException

A Gbangoo should jump to the current location of the player and produce the prepared Gube.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the Gbangoo owned

Returns:

the Gube produced

Throws:

APIException - fails if the session key is wrong,
or if the Gbangoo does not exist,
or if the Gbangoo is not owned by the authenticated player

locate

Feature locate(java.lang.String sessionKey,
               float latitude,
               float longitude)
               throws APIException

Retrieve the geographical location of a given cell.

Parameters:

sessionKey - the session key of the authenticated user

latitude - the latitude

longitude - the longitude

Returns:

a KML-like position description (cf. Placemark tag)

Throws:

APIException - fails if the session key is wrong,
or, if the coordinates were not visited by the authenticated player
or, if the coordinates are invalid

login

WebSession login(java.lang.String playerName,
                 java.lang.String password)
                 throws APIException

Authenticates and generates a session key.

Parameters:

playerName - the username of the player

password - the password for the indicated player

Returns:

a session attached to the player

Throws:

APIException - thrown if player does not exist or if password was wrong

logout

void logout(java.lang.String sessionKey)
            throws APIException

Close a currently open session by indicating the sessionKey.

Parameters:

sessionKey - the 256-digit generated session key

Throws:

APIException - if session does not exist

mail

Message mail(java.lang.String sessionKey,
             java.lang.String receivingPlayer,
             java.lang.String message)
             throws APIException

Send a Message to a remote Player.

Parameters:

sessionKey - the session key of the authenticated Player

receivingPlayer - the name of the remote Player to chat with

message - the content of the message

Returns:

the message sent to the remote Player

Throws:

APIException - if the given session key is invalid, or
the Player name is unknown, or
the message content is inappropriate

makeProductItemAvailableTo

void makeProductItemAvailableTo(java.lang.String sessionKey,
                                long productItemId,
                                java.lang.String player,
                                boolean available)
                                throws APIException

Collect a resource.

Parameters:

sessionKey - the key of the session of the Player who is collecting the item

productItemId -

player -

available -

Throws:

APIException - if the session key is invalid, or
there is no product item with the given id, or
the player name is unknown, or
the requesting player is not the creator of the product item

mine

Gbangoo mine(java.lang.String sessionKey,
             long gbangooId)
             throws APIException

A Gbangoo starts mining at its current location.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the id of the Gbangoo that should start mining

Returns:

the updated Gbangoo object

Throws:

APIException - fails if the session key is wrong,
or, if the Gbangoo is not owned by the authenticated player,
or, if the Gbangoo cannot mine (eg. busy, in inventory, tile not available)

move

Event move(java.lang.String sessionKey,
           long entityId,
           long direction)
           throws APIException

Move a placeable Entity towards a given direction

Parameters:

sessionKey - the session key of the authenticated Player

entityId - the id to the placeable Entity to move

direction - the direction to move towards

Returns:

the movement Event

Throws:

APIException - if the session key is invalid, or
the Entity id is unknown, or
the Entity is not placeable, or
the direction is invalid

notify

void notify(java.lang.String sessionKey,
            java.lang.String player,
            java.lang.String title,
            java.lang.String description,
            long avatar,
            boolean shareable)
            throws APIException

Sends a notification message to a player. The message consists of a title, a description, an optional avatar and an additional flag that indicates whether this notification is recommended for being shared with others.

Parameters:

sessionKey - the key of the session of the Player that owns the entity

player - the name of the Player to be notified

title - the title of the notification

description - the description of the notification

avatar - the avatar image that should be included with the notification (or 0 if no image shall be included)

shareable - a flag that indicates whether this notification is recommended for being shared with others

Throws:

APIException - if the session key is invalid, the player name is unknown, or if no such title, description or avatar can be found

offerFriendship

Player offerFriendship(java.lang.String sessionKey,
                       java.lang.String player,
                       java.lang.String introduction)
                       throws APIException

Offer friendship to another player. Has to wait for an accepting answer.

Parameters:

sessionKey - the session key of the authenticated user

player - the possibly new friend

introduction - an initial phrase ("optional": if not indicated, use an empty string)

Returns:

the reference of a hopefully new friend

Throws:

APIException - fails if the session key is wrong,
or, if the player is unknown

pick

Pocket pick(java.lang.String sessionKey,
            long tagId)
            throws APIException

Pick up a copy of a tag

Parameters:

sessionKey - the session key of the authenticated user

tagId - the id of the tag to take

Returns:

updated information about that pocket

Throws:

APIException - if the session key does not exist, or
the tag id does not exist

piece

Tile piece(java.lang.String sessionKey,
           long tagId,
           long tileId)
           throws APIException

Create a tag at a given position.

Parameters:

sessionKey - the session key of the authenticated user

tagId - the id of the tag to drop

tileId - the id of the tile to drop the tag onto

Returns:

updated information about the tile

Throws:

APIException - if the session key does not exist, or
the tile id does not exist, or
the tag id does not exist

playCard

Challenge playCard(java.lang.String sessionKey,
                   long challengeId,
                   long tagId)
                   throws APIException

Play a given card in a given match.

Parameters:

sessionKey - the session key of the authenticated user

challengeId - the match to play the card in

tagId - the tag to play

Returns:

the updated match sheet

Throws:

APIException - fails if the session key is wrong,
or if the challenge indicated is unknown,
or if the tag indicated is unknown

playSound

void playSound(java.lang.String sessionKey,
               java.lang.String name,
               long melodyId)
               throws APIException

Plays a sound on the device of the given Player if logged in and if settings allow.

Parameters:

sessionKey - the key of the session of the chummy Player

name - the name of the Player that should experience the sound

melodyId - the id of the melody

Throws:

APIException - if the session key is invalid, the player name is unknown or not a friend or the id of the melody is invalid

postOffer

Trade postOffer(java.lang.String sessionKey,
                long tradeId)
                throws APIException

Sends the created offer to the trading partner.

Parameters:

sessionKey - the session key of the authenticated user

tradeId - the offer to be sent

Returns:

the offer sent

Throws:

APIException - fails if the session key is wrong,
or, if the trade id is unknown

prepareOffer

Trade prepareOffer(java.lang.String sessionKey,
                   java.lang.String partnerName)
                   throws APIException

Prepare a trade (initial offer or re-offer) with a given player.

Parameters:

sessionKey - the session key of the authenticated user

partnerName - the requested trading partner

Returns:

the initially empty referring trading object

Throws:

APIException - if the partner with the indicated name does not exist

rateCell

Cell rateCell(java.lang.String sessionKey,
              long cellId,
              byte rating,
              java.lang.String comment)
              throws APIException

Rate a given cell.

Parameters:

sessionKey - the session key of the authenticated user

cellId - the id of the cell for the rating

rating - the personal rating value

comment - an optional comment

Returns:

the updated cell object

Throws:

APIException - fails if the session key is wrong,
or, if the cell was not visited by the authenticated player
or, if the id of the cell is unknown
or, if the rating is invalid

rateTag

Tag rateTag(java.lang.String sessionKey,
            long tagId,
            byte rating,
            java.lang.String comment)
            throws APIException

Vote for the rating of a Cell.

Parameters:

sessionKey - the session key of the authenticated Player

tagId - the id of the Tag to rate

rating - the given rating

comment - an optional semi-colon separated comment

Returns:

the updated Tag

Throws:

APIException - if the given session key is invalid, or
the Tag id is unknown, or
the rating is invalid, or
the comment is inappropriate

register

void register(java.lang.String playerName,
              java.lang.String password,
              java.lang.String cellPhone,
              java.lang.String email,
              java.lang.String model,
              java.lang.String language,
              java.lang.String method)
              throws APIException

Request a membership for the given person with the given details.

Parameters:

playerName - the username of the player

password - the password

cellPhone - the cell phone number including international predial code

email - a correct email address to submit the confirmation to

model - the model of the cell phone

language - the language the person wants to receive texts in

method - the sign up method, e.g. website, mobile, in-game

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

registerFB

void registerFB(java.lang.String playerName,
                java.lang.String fbuid,
                java.lang.String fbsession,
                java.lang.String model,
                java.lang.String language,
                java.lang.String method)
                throws APIException

Request a membership for the given person with the given details.

Parameters:

playerName - the username of the player

fbuid - the facebook user id

fbsession - the facebook offline session key

model - the model of the cell phone

language - the language the person wants to receive texts in

method - the sign up method, e.g. website, mobile, in-game

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

registerFQ

void registerFQ(java.lang.String playerName,
                java.lang.String fquid,
                java.lang.String fbsession,
                java.lang.String model,
                java.lang.String language,
                java.lang.String method)
                throws APIException

Request a membership for the given person with the given details.

Parameters:

playerName - the username of the player

fquid - the foursquare user id

fbsession - the foursquare session key

model - the model of the cell phone

language - the language the person wants to receive texts in

method - the sign up method, e.g. website, mobile, in-game

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

registerLess

void registerLess(java.lang.String playerName,
                  java.lang.String iphoneid,
                  java.lang.String model,
                  java.lang.String language,
                  java.lang.String method)
                  throws APIException

Register a player with the iphone id as the identifier.

Parameters:

playerName - the username of the player

iphoneid - the iphone unique id

model - the model of the cell phone

language - the language the person wants to receive texts in

method - the sign up method, e.g. website, mobile, in-game

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

registerTwitter

void registerTwitter(java.lang.String playerName,
                     java.lang.String tuid,
                     java.lang.String fbsession,
                     java.lang.String model,
                     java.lang.String language,
                     java.lang.String method)
                     throws APIException

Request a membership for the given person with the given details.

Parameters:

playerName - the username of the player

tuid - the twitter user id

fbsession - the twitter session key

model - the model of the cell phone

language - the language the person wants to receive texts in

method - the sign up method, e.g. website, mobile, in-game

Throws:

APIException - thrown if player name is taken, the password is not verified or the cellPhone or email are invalid

remindPassword

void remindPassword(java.lang.String phoneOrEmail)
                    throws APIException

Request a password reminder message to an email address or a cell phone.

Remark: There is no warning if the phone number or email address are unregistered Players.

Parameters:

phoneOrEmail - a valid phone number or an email.

Throws:

APIException - if the format of the phone number or the email is incorrect.

removeMemory

void removeMemory(java.lang.String sessionKey,
                  java.lang.String entityId,
                  java.lang.String key)
                  throws APIException

Remove a key-value pair from a Entity's memory.

Parameters:

sessionKey - the session key of the authenticated Player

entityId - the id/name of the Entity which memory should be modified

key - the key to remove

Throws:

APIException - if the session key is invalid, or
the Entity id is unknown, or
the key is invalid

renameCell

Cell renameCell(java.lang.String sessionKey,
                long cellId,
                java.lang.String name)
                throws APIException

Gives a new name to a given cell.

Parameters:

sessionKey - the session key of the authenticated user

cellId - the id of the cell with a new name

name - the new name

Returns:

the updated cell object

Throws:

APIException - fails if the session key is wrong,
or, if the cell was not discoveredby the authenticated player
or, if the id of the cell is unknown
or, if the name is invalid, already taken or inappropriate

reportBug

int reportBug(java.lang.String author,
              java.lang.String content,
              int severity)
              throws APIException

Post a bug report indicating the author, a problem description and the severity.

Parameters:

author - a (registered) author (email, cellphone number or Gbanga username)

content - a precise problem description

severity - a severity level

Returns:

the unique bug id that has been generated for this bug

Throws:

APIException - if the author, the content or the severity level are invalid

See Also:

BUG_SEVERITY_CRITICAL, BUG_SEVERITY_MAJOR, BUG_SEVERITY_NORMAL, BUG_SEVERITY_MINOR, BUG_SEVERITY_TRIVIAL, BUG_SEVERITY_ENHANCEMENT

reportPlayer

Report reportPlayer(java.lang.String sessionKey,
                    java.lang.String player,
                    java.lang.String explanation)
                    throws APIException

Report an incident about a player that didn't comply with the regulations (rudeness in chat messages, privacy tricks, fraud, creating dangerous quests, etc.).

Remark: Anonymous reports without a valid session key are logged, but not read nor taken action upon

Parameters:

sessionKey - the session key of the authenticated user

player - the player that was the reason for the incident

explanation - an verbose description of the incident

Returns:

a receipt of the report

Throws:

APIException - if no player with the given id exists

requestDownloadSMS

DownloadRequest requestDownloadSMS(java.lang.String playerName,
                                   java.lang.String password)
                                   throws APIException

Request a message with the download location for the client software.

Parameters:

playerName - the username of the player

password - the password for the indicated player

Returns:

a DownloadRequest object

Throws:

APIException - if the service is currently not available or the session key is invalid.

requestDownloadSMSByHeader

DownloadRequest requestDownloadSMSByHeader(java.lang.String playerName,
                                           java.lang.String password,
                                           java.lang.String header)
                                           throws APIException

Same as requestDownloadSMS(String, String) but also uses the given http header to guess the user's device.

Parameters:

playerName - the username of the player

password - the password for the indicated player

header - the http header

Returns:

a DownloadRequest object

Throws:

APIException

requestDownloadSMSBySessionKey

DownloadRequest requestDownloadSMSBySessionKey(java.lang.String sessionKey)
                                               throws APIException

Request a message with the download location for the client software.

Parameters:

sessionKey - the session key

Returns:

a DownloadRequest object

Throws:

APIException - if the service is currently not available or the session key is invalid.

requestPurchasedItem

void requestPurchasedItem(java.lang.String sessionKey,
                          java.lang.String appleProductId,
                          java.lang.String transactionId,
                          java.lang.String receipt)
                          throws APIException

Counts the entities containing a specific entry in the memory db.

Parameters:

sessionKey - the temporarily valid key of a player's session

appleProductId - the memory key

transactionId - the value to filter with

receipt - the receipt provided by apple

Throws:

APIException

resume

WebSession resume(java.lang.String playerName,
                  java.lang.String sessionKey)
                  throws APIException

Password-less resume into existing session.

Parameters:

playerName - the username of the player

sessionKey - the temporarily valid session key of that player's session

Returns:

a session attached to the player

Throws:

APIException - thrown if player does not exist, the session was closed or not existing

reward

void reward(java.lang.String sessionKey,
            java.lang.String player,
            int points)
            throws APIException

Reward the given Player with points.

Parameters:

sessionKey - the key of the session of the Player who requests a reward for the give player

player - the Player to reward

points - the number of points to reward

Throws:

APIException - if the session key is invalid or the player to reward is unknown

setCode

boolean setCode(java.lang.String key,
                long id,
                java.lang.String code)
                throws APIException

Applies a "download code" for the given entity.

Parameters:

key - the key of the session of the Player that owns the entity

id - the id of the entity to apply a download code for

code - a code of your choice (or null to remove download code)

Returns:

if the indicated code was available, it returns true, if it is already used it returns false

Throws:

APIException - if the session key is invalid, the entity unknown or not owned by the requesting Player or the download code inappropriate, too long or invalid

setMemory

void setMemory(java.lang.String sessionKey,
               java.lang.String entityId,
               java.lang.String key,
               java.lang.String value)
               throws APIException

Add a key-value pair to a Entity's memory.

Parameters:

sessionKey - the session key of the authenticated Player

entityId - the id/name of the Entity which memory should be modified

key - the key name to add

value - the value to the key

Throws:

APIException - if the session key is invalid, or
the Entity id is unknown, or
the key is invalid, or
the value is inappropriate

setMemoryForAll

void setMemoryForAll(java.lang.String sessionKey,
                     java.lang.String key,
                     java.lang.String value)
                     throws APIException

Set a key-value pair to all the Entity's memory having the key.

Parameters:

sessionKey - the session key of the authenticated Player

key - the key name to set

value - the value to the key

Throws:

APIException - if the session key is invalid, or
the value is inappropriate

setTradable

void setTradable(java.lang.String sessionKey,
                 long entityId,
                 boolean yes)
                 throws APIException

Sets if a given entity is tradable.

Parameters:

sessionKey - the key for the session of the owning Player

entityId - the id of the entity to modify the tradable status

yes - true to make it tradable

Throws:

APIException - if the session key is invalid, the entity id unknown or the entity not owned by the current player

shout

Message shout(java.lang.String sessionKey,
              java.lang.String receivingCell,
              java.lang.String message)
              throws APIException

Shout a text Message to a Cell.

Parameters:

sessionKey - the session key of the authenticated Player

receivingCell - the name of the Cell to shout at

message - the content of the message

Returns:

the message shouted to the cell

Throws:

APIException - if the given session key is invalid, or
the Cell name is unknown, or
the message content is inappropriate

showTicker

void showTicker(java.lang.String sessionKey,
                java.lang.String name,
                java.lang.String ticker)
                throws APIException

Shows a ticker message on the device of the given Player if logged in and if settings allow.

Parameters:

sessionKey - the key of the session of the chummy Player

name - the name of the Player that should receive the ticker message

ticker - a message to be shown

Throws:

APIException - if the session key is invalid, the player name is unknown or not a friend or the id of the message is inappropriate

speak

Event speak(java.lang.String sessionKey,
            long gbangooId,
            java.lang.String message)
            throws APIException

Lets the given Gbangoo send the message to everyone in its current cell.

Parameters:

sessionKey - the session key of the authenticated Player

gbangooId - the id of the sending Gbangoo

message - the content of the message

Returns:

the Conversation Event

Throws:

APIException - if the session key is invalid, or
the Gbangoo id is unknown, or
the message is inappropriate

speakTo

Event speakTo(java.lang.String sessionKey,
              long gbangooId,
              java.lang.String player,
              java.lang.String message)
              throws APIException

Lets the given Gbangoo send a message to the specified player.

Parameters:

sessionKey - the session key of the authenticated Player

gbangooId - the id of the receiving Gbangoo

player - the player to whom to send the message

message - the content of the message

Returns:

the Conversation Event

Throws:

APIException - if the session key is invalid, or
the Gbangoo id is unknown, or
the message is inappropriate

stop

Gbangoo stop(java.lang.String sessionKey,
             long gbangooId)
             throws APIException

Halts the given Gbangoo.

Parameters:

sessionKey - the session key of the authenticated user

gbangooId - the id of the Gbangoo that should stop

Returns:

the updated Gbangoo object

Throws:

APIException - fails if the session key is wrong,
or, if the Gbangoo is not owned by the authenticated player

submitStatistics

void submitStatistics(java.lang.String sessionKey,
                      java.lang.String data)

This method is used to submit statistics for research purposes. It is used for demographics and other data. The structure of the data is defined internally by Gbanga, Millform AG.

Parameters:

sessionKey - the key of the session to post statistics for

data - statistiscal data

subscribeToWebHook

java.lang.String subscribeToWebHook(java.lang.String sessionKey,
                                    int event,
                                    java.lang.String filter,
                                    java.lang.String url)
                                    throws APIException

Registers a Web Hook listener at the given URL for the given user. Note: registrations survive a login session.

Parameters:

sessionKey - the key of the session to register the listener for

event - the event type for which to subscribe

filter - the filter that received events are required to match

url - the location of the Web Hook listener

Returns:

Some information based on the "standards" described on http://webhooks.pbworks.com/RESTful-WebHooks

Throws:

APIException - If an error occurred during subsription

takeOverCell

int takeOverCell(java.lang.String sessionKey,
                 java.lang.String playerName,
                 java.lang.String cellName,
                 java.lang.String newOwner)
                 throws APIException

Transfer the ownership of a cell to a new family

Parameters:

sessionKey - the session key of a logged in super user

playerName - the player that is taking over

cellName - the cell name

newOwner - the name of the family that now is the owner of this cell

Returns:

the number of transfered infrastructures

Throws:

APIException - thrown if the sessionKey doesn't have the required privileges of the cellId is unknown

trade

Trade trade(java.lang.String sessionKey,
            java.lang.String partnerName,
            java.lang.String offeredGoodIdString,
            java.lang.String requestedGoodIdString)
            throws APIException

Add goods to the indicated offer.

Parameters:

sessionKey - the session key of the authenticated user

partnerName - the requested trading partner

offeredGoodIdString - an array of ids of a goods to offer (may be 0, if nothing to offer)

requestedGoodIdString - an array of ids of a good that are being requested (may be 0, if nothing is requested)

Returns:

the updated referring trading object

Throws:

APIException - fails if the session key is wrong,
or, if the partner with the indicated name does not exist,
or, the offered good id is unknown,
or, the requested good id is unknown

transferInfrastructuresAndCells

int transferInfrastructuresAndCells(java.lang.String sessionKey,
                                    java.lang.String playerName,
                                    java.lang.String newFamily)
                                    throws APIException

Transfer the infrstructures owned by a player from a family to another one

Parameters:

sessionKey - the session key of a logged in super user

playerName - the name of the player

newFamily - the name of the new family

Returns:

the number of transfered cells

Throws:

APIException - thrown if the sessionKey doesn't have the required privileges

unsubscribeFromWebHook

java.lang.String unsubscribeFromWebHook(java.lang.String sessionKey,
                                        java.lang.String url)
                                        throws APIException

Unregisters a Web Hook listener at the given URL for the given user. Note: registrations survive a login session.

Parameters:

sessionKey - the key of the session to register the listener for

url - the location of the Web Hook listener

Returns:

Some information based on the "standards" described on http://webhooks.pbworks.com/RESTful-WebHooks

Throws:

APIException - If an error occurred during un-subscription

updateAvatar

void updateAvatar(java.lang.String sessionKey,
                  long entityId,
                  java.io.InputStream is)
                  throws APIException

Updates the image of a given entity.

Parameters:

sessionKey - the key of the session requesting the update

entityId - the id of the entity that needs a new avatar

is - the stream with the avatar data

Throws:

APIException - if session key is invalid, the entity is unknown or not owned nor created by the current Player or the input stream invalid

updateAvatarByRef

void updateAvatarByRef(java.lang.String sessionKey,
                       long entityId,
                       long avatarId)
                       throws APIException

Sets the image of a given entity by referencing an existing image.

Note that after updating the avatar using this method, updating the avatar image will change the entity's avatar, and, conversely, updating the entity's avatar by specifying an image will update the avatar of other entities referencing the same image.

Parameters:

sessionKey - the key of the session requesting the update

entityId - the id of the entity that needs a new avatar

avatarId - the id of the existing avatar image

Throws:

APIException - if session key is invalid, the entity is unknown or not owned nor created by the current Player or the existing avatar may not be used by the requester

updateDescription

void updateDescription(java.lang.String sessionKey,
                       long entityId,
                       java.lang.String description)
                       throws APIException

Sets the description field of the given entity. This descriptive text is shown on tooltips, in about windows and thelike.

Parameters:

sessionKey - the key of the session of the owning Player

entityId - the id of the entity which needs a new description

description - the descriptive text (might have some formatting)

Throws:

APIException - if the session key is invalid, the entity id unknown or not owned by the requesting Player or the descriptive text inappropriate

updateEmail

void updateEmail(java.lang.String sessionKey,
                 java.lang.String playerName,
                 java.lang.String email)
                 throws APIException

Update the email of a Player.

Parameters:

sessionKey - the session key of the authenticated Player

playerName - the name of the target player, empty to target self.

email - a valid email address

Throws:

APIException - if the session key is invalid, or
the email address has a wrong format

updateGbangooType

void updateGbangooType(java.lang.String sessionKey,
                       long type,
                       java.io.InputStream avatar,
                       java.lang.String description,
                       java.lang.String comment)
                       throws APIException

Updates an existing Gbangoo type. Any of the type properties may be updated, whereby a value of null for a property implies that that property will not be updated.

Parameters:

sessionKey - the session key of the authenticated Player

type - the numerical id uniquely identifying the type to update

avatar - the new avatar image displayed for Gbangoos of the specified type

description - the new description displayed for Gbangoos of the specified type

comment - an optional comment describing the purpose of the specified type

Throws:

APIException - if the session key is invalid, or
the specified type is invalid, or
the description is inappropriate, or
the avatar binary is corrupt

updateInfrastructureType

void updateInfrastructureType(java.lang.String sessionKey,
                              long type,
                              java.io.InputStream avatar,
                              java.lang.String description,
                              java.lang.String comment)
                              throws APIException

Updates an existing Infrastructure type. Any of the type properties may be updated, whereby a value of null for a property implies that that property will not be updated.

Parameters:

sessionKey - the session key of the authenticated Player

type - the numerical id uniquely identifying the type to update

avatar - the new avatar image displayed for infrastructures of the specified type

description - the new description displayed for infrastructures of the specified type

comment - an optional comment describing the purpose of the specified type

Throws:

APIException - if the session key is invalid, or
the specified type is invalid, or
the description is inappropriate, or
the avatar binary is corrupt

updateProfile

Player updateProfile(java.lang.String sessionKey,
                     java.lang.String cellphone,
                     java.lang.String email)
                     throws APIException

Update the details of a Player.

Parameters:

sessionKey - the session key of the authenticated Player

cellphone - the cell phone in a valid format (+12 3456 789) which includes the country code

email - a valid email address

Returns:

the updated Player object

Throws:

APIException - if the session key is invalid, or
the cell phone or the email address has a wrong format, or
the Twitter account credentials could not be verified, or
the Facebook User ID is invalid

updateProfileImage

void updateProfileImage(java.lang.String sessionKey,
                        java.io.InputStream image)
                        throws APIException

Update the profile image of the authenticated Player.

Parameters:

sessionKey - the session of the Player with the profile image that needs to be updated

image - the image data as a binary

Throws:

APIException - if the session is invalid or the image could not be parsed

updateResourceType

void updateResourceType(java.lang.String sessionKey,
                        long type,
                        java.lang.String screenname,
                        java.io.InputStream avatar,
                        java.lang.String description)
                        throws APIException

Updates an existing Resource type. Any of the type properties may be updated, whereby a value of null for a property implies that that property will not be updated.

Parameters:

sessionKey - the session key of the authenticated Player

type - the numerical id uniquely identifying the type to update

screenname - the screen name displayed for resources of the specified type

avatar - the new avatar image displayed for resources of the specified type

description - the new description displayed for resources of the specified type

Throws:

APIException - if the session key is invalid, or
the specified type is invalid, or
or
the screen name or description is inappropriate, or
the avatar binary is corrupt

updateStatus

Player updateStatus(java.lang.String sessionKey,
                    java.lang.String status)
                    throws APIException

Updates the status message of a Player in a manner similar to a Twitter message, Facebook's status or a tagline in any instant messenger (eg, MSN and Skype).

Parameters:

sessionKey - the session of the Player with the profile image that needs to be updated

status - a valid status message

Returns:

the updated Player object

Throws:

APIException - if the session key is invalid, or
the status message is inappropriate, too short or too long

whereAmI

Feature whereAmI()

Tries to locate the requester of this method with the help of HTTP header information, IP localization, etc.

Returns:

the place within the game where the requesting party is currently in