Revision as of 23:13, 22 July 2020

 !!!! WIP !!!!

There are currently still 80 articles in preparation in the category "WIP"

Article in preparation. Please let the author finish it before you modify it.
The last editing was from Dorothée on 22.07.2020.

---

This page is the Ryzom Forge version of api.ryzom.com site

According to Wikipedia, an An API or "Application Programming interface" is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc. [...]Through information hiding, APIs enable modular programming, which allows users to use the interface independently of the implementation.

In our case: Ryzom API is an URL based system to get some Ryzom in-game information like game time, character, guild profile... API changes log can be found on forum.

Basics

Base URL

All requests are using https://api.ryzom.com as base url.

API keys

• API keys are 41 alphanumeric characters. Character keys start with 'c' and guild keys with 'g'.
• API keys must be created using "RyzomAPI app": https://app.ryzom.com/app_ryzomapi
• You must be guild leader or high officer to manage and view guild api key.

PHP API

PHP API library can be found in the ryzomapi_lite repository.

Third party libraries

(PHP) Sheet translations and info about resources can be found from the https://github.com/nimetu/ryzom_extra repository. The json-resources branch has data in JSON format.

python Interface ?

Functions

Time

To know the time and date in Ryzom.

Usage

<base URL>/time.php

URL Parameters

format

(optional), defaults ro raw.

• raw : Returns the tick. The server tick is a 32 bit integer that increases by one every 100 milliseconds.
• txt : Returns a homine-readable string.
• xml : Returns an xml file that contains all shard time information.

Cache duration

The data is cached for 1 minute.

XML structure

<shard_time>
  <server_tick>514105152</server_tick>
  <jena_year>2576</jena_year>
  <day_of_jy>319</day_of_jy>
  <month_of_jy>10</month_of_jy>
  <cycle>0</cycle>
  <day_of_cycle>319</day_of_cycle>
  <month_of_cycle>10</month_of_cycle>
  <day_of_month>19</day_of_month>
  <day_of_week>1</day_of_week>
  <season>3</season>
  <day_of_season>49</day_of_season>
  <time_of_day>13</time_of_day>
  <txt_en>13h - Dua, Mystia 20, 1st AC 2576</txt_en>
  <txt_fr>13h - Dua, Mystia 20, 1er CA 2576</txt_fr>
  <txt_de>13h - Dua, Mystia 20, 1. AZ 2576</txt_de>
  <cache created="1387437183" expire="1387437243"/>
</shard_time>

PHP interface

ryzom_time_api() : Returns SimpleXMLElement or boolean false on failure.

<?php
  require_once "ryzomapi_lite.php";

  $time = ryzom_time_api('xml');
  if ($time !== false) {
    $txt_en = htmlspecialchars($time->txt_en);
    echo "Atys time is {$txt_en}";
  } else {
    echo "API failure";
  }
?>

Character

Access character information.

Usage

<base URL>/character.php?apikey=key
<base URL>/character.php?apikey[=key1&apikey[]=key2

URL Parameters

apikey

Character API key starting with 'c'

Cache Duration

<character> xml element has attributes *created* and *cached_until* (utc timestamp)

XML structure

API is able to return information about multiple characters at once and so each <character> element is child of <ryzomapi> root element:

<ryzomapi>
  <character apikey="key1" created="1387369332" modules="C01:P01" cached_until="1387369632">
    ....
  </character>
  <character apikey="key2" created="1387369332" modules="P01" cached_until="1387369632">
    ....
  </character>
</ryzomapi>

Invalid key error:

<character apikey="key1" created="1387369873">
  <error code="404">invalid key</error>
</character>

Possible error codes are listed on API error codes.

PHP interface

ryzom_character_api($apikey)

$apikey can be either string (single key) or array of strings.

On success, function returns associative array of SimpleXMLElement with apikey as array index.

On failure, function returns boolean false.

<?php
require_once "ryzomapi_lite.php";

function info($char) {
  if (isset($char->error)) {
    $apikey = htmlspecialchars($char['apikey']);
    $error = htmlspecialchars($char->error);
    $code = (int)$char->error['code'];
    echo "Character API key '{$apikey}' failed: {$code}:{$error}";
  } else {
    $name = htmlspecialchars($char->name);
    echo "Character name: {$name}";
  }
}

$apikey = 'cABCDEF';
$chars = ryzom_character_api($apikey);
if ($chars !== false) {
  info($chars[$apikey]);
} else {
  echo "Character API failed";
}

$apikeys = ['cABCDEF', 'c123456'];
$chars = ryzom_character_api($apikeys);
if ($chars !== false) {
  foreach($chars as $char) {
    info($char);
  }
} else {
  echo "Character API failed";
}

Guilds

Displays the list of all guilds.

Usage

<base URL>/guilds.php

Cache Duration

Returned XML has <cache> element with attributes created and expire (utc timestamp)

XML structure

<guilds>
  <cache created="1387371064" expire="1387374664"/>
  <shard>atys</shard>
  <guild>
    <gid>105906182</gid>
    <name>Atrium</name>
    <race>Fyros</race>
    <icon>575080624687965565</icon>
    <creation_date>131736955</creation_date>
    <description>Here you are the Keeper, your destiny is to make the rules to be respected</description>
  </guild>
  <guild>
    ....
  </guild>
</guilds>

PHP interface

ryzom_guildlist_api()

Function returns SimpleXMLElement object on success or boolean false on error.

<?php
  require_once "ryzomapi_lite.php";

  $guilds = ryzom_guildlist_api();
  if ($guilds !== false) {
    echo '<pre>';
    foreach($guilds->guild as $guild) {
      $gid = (int)$guild->gid;
      $name = htmlspecialchars($guild->name);
      echo "{$gid} {$name}\n";
    }
    echo '</pre>';
  } else {
    echo "API failure";

Guild

Access to guild information.

Usage

<base URL>/guild.php?apikey=key
<base URL>/guild.php?apikey[]=key1&apikey[]=key2

URL Parameters

apikey 

Guild API key starting with 'g'

Cache Duration

Guild xml element has attributes created and cached_until (utc timestamp)

XML structure

API is able to return information for multiple guilds at once and so each <guild> element is a child of <ryzomapi> root elements

<ryzomapi>
  <guild apikey="key1" created"1387369332" modules="G01:G02:G03:G04:P01" cached_until="1387369632">
    ...
  </guild>
  <guild apikey="key2" created"1387369332" modules="P01" cached_until="1387369632">
    ...
  </guild>
</ryzomapi>

Invalid key error:

<guild apikey="key1" created="1387369873">
  <error code="404">invalid key</error>
</guild>

Possible error codes are listed on API error codes.

PHP interface

ryzom_guild_api($apikey)

$apikey can be either a string or array of strings

Function will return associative array of SimpleXMLElement with $apikey as array index On failure function returns boolean false

<?php
require_once "ryzomapi_lite.php";

function info($guild) {
  if (isset($guild->error)) {
    $apikey = htmlspecialchars($guild['apikey']);
    $error = htmlspecialchars($guild->error);
    $code = (int)$guild->error['code'];
    echo "Guild API key '{$apikey}' failed: {$code}:{$error}";
  } else {
    $name = htmlspecialchars($guild->name);
    echo "Guild name: {$name}";
  }
}

$apikey = 'gABCDEF';
$guilds = ryzom_guild_api($apikey);
if ($guilds !== false) {
  info($guilds[$apikey]);
} else {
  echo "Guild API failed";
}

$apikeys = ['gABCDEF', 'g123456'];
$guilds = ryzom_guild_api($apikeys);
if ($guilds !== false) {
  foreach($guilds as $guild) {
    info($guild);
  }
} else {
  echo "Guild API failed";
}

API error codes

404 invalid api key 

No such API key.

403 key expired 

API key is valid, but has expired

503 character data is not initialized

503 guild data is not initialized

Temporary server side error indicating that character/guild info is currently not available.

Data will be available after character has logged in to game

Tools

Render

Guild icon

Item icon

In Game

AppZone

In-game browser

WikipAtys

Wiki implemetation

Pages in Category : "API templates" :

• Template:APIitemIcon
• Template:APIguildIcon
• Template:OPguildIcon

Links and Examples

• Example page and php library sources : https://bitbucket.org/nimetu/ryzomapi_lite
• Live working example page (Ballistic Mystix) : http://ryapp.bmsite.net/
• API discussion in forum : http://app.ryzom.com/app_forum/index.php?page=topic/view/18541
• the App (Appzone) Api key to create and get a key: https://app.ryzom.com/app_ryzomapi/index.php?

Portal of the Forge of Ryzom