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