Ryzom API

Материал из ЭнциклопАтис

Перейти к: навигация, поиск
de:Ryzom API en:Ryzom API es:Ryzom API fr:Ryzom API ru:Ryzom API
Translation to review
Don't blame the contributors, but come and help them 😎

Reference text ( Maintained text, used as reference ) :
Notes: (Leda, 2022-05-24)

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

According to Wikipedia, 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.


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 library can be found in the ryzom API client repository.

Third party libraries

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

python Interface ?



To know the time and date in Ryzom.


<base URL>/time.php

URL Parameters

(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

  <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"/>

PHP interface

ryzom_time_api() : Returns SimpleXMLElement or boolean false on failure.
  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";


Access character information.


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

URL Parameters

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:

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

Invalid key error:

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

Possible error codes are listed on API error codes.

PHP interface

$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.
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) {
} else {
  echo "Character API failed";
$apikeys = ['cABCDEF', 'c123456'];
$chars = ryzom_character_api($apikeys);
if ($chars !== false) {
  foreach($chars as $char) {
} else {
  echo "Character API failed";


Displays the list of all guilds.


<base URL>/guilds.php

Cache Duration

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

XML structure

  <cache created="1387371064" expire="1387374664"/>
    <description>Here you are the Keeper, your destiny is to make the rules to be respected</description>

PHP interface


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

  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";


Access to guild information.


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

URL Parameters

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

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

Invalid key error:

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

Possible error codes are listed on API error codes.

PHP interface


$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

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) {
} else {
  echo "Guild API failed";

$apikeys = ['gABCDEF', 'g123456'];
$guilds = ryzom_guild_api($apikeys);
if ($guilds !== false) {
  foreach($guilds as $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



This is a set of PHP function to render a web page using Ryzom style.

CSS file

You need to manually include ryzom css file :

<link href="https://api.ryzom.com/data/css/ryzom_ui.css" rel="stylesheet" media="all">

PHP interface

ryzom_render_window($title, $content, array $links)

Returns html markup resembling ingame window style

$links - (optional) associative array that defines right side buttons on window title bar
require_once "ryzomapi_lite.php";

$links = array(
  array('href' => 'http://www.ryzom.com/', 'text' => 'Ryzom website'),
  array('href' => 'http://app.ryzom.com/app_ryzomapi/', 'text' => 'RyzomAPI app'),

echo ryzom_render_window('Title', 'Hello World!', $links);

Guild icon

Retrieves a guild icon


<base URL>/guild_icon.php?icon=:icon&size=:size

URL Parameters

It's a raw 64bit number from Character xml or Guild list xml file
size (optional)
s (default) Small guild icon (32x32 pixels)
b Big guild icon (64x64 pixels)

Cache Duration

It's cached for ever. Since the icon is unique and never changes. For a specific icon, it'll always return the same image.

PHP interface

ryzom_guild_icon_url($icon, $size)

Returns a string that contains the url to display a guild icon.

require_once "ryzomapi_lite.php";

$url = ryzom_guild_icon_url("4505559206514131", 'b');
echo "<img src=\"$url\" alt=\"\">";

Item icon

Retrieves Item icons (see also: Ryzom API/Item sheetids)


<base URL>/item_icon.php?sheetid=iczahp_3.sitem&c=1&q=0&s=0&sap=-1&destroyed=0&label=1&locked=0

URL Parameters

Parameter Description Default Example icon
sheetid It's the id of an item that you can find in the Character xml file.
For example, iczahp_3.sitem is a valid sheetid.
sheetids can me found in Nimetu's ryzom_extra repository
c (optional), default is 1
The color of the item. It's a value between 0 and 7
0 1 2 3
4 5 6 7
q (optional), default is 0
The quality of the item.
0 120
s (optional), default is 0
The size of the stack.
0 53
sap (optional) number of sap plus 1 of the item.
-1 = (default) No sap icon, no number
0 = sap icon, no number
-1 0 1 2 8
destroyed (optional) displays the item as if it was destroyed (with a red cross)
0 = (default)
0 1
label (optional), draws icon text if present
1 = (default)
0 1
locked (optional) display the item as if it was locked by the owner
0 = (default)
0 1

Cache Duration

It's cached for ever. Since the icon is unique and never change. For a specific icon, it'll always return the same image.

PHP interface

ryzom_item_icon_url($sheetid, $c=-1, $q=0, $s=0, $sap=-1, $destroyed=false, $label=true, $locked=false)

Returns a string that contains the url to display a item icon.

require_once "ryzomapi_lite.php";

$url = ryzom_item_icon_url('iczahp_3.sitem', 2);

echo "<img src=\"{$url}\" alt=\"\">";

In Game


User authentication for apps registered in AppZone


URL values
user -- base64 encoded php serialized array
checksum -- sha1 hash_hmac with app secret key from AppZone

Because of php serialize, checksum must be validated before user value can be safely used.
A validating checksum will also give a strong guarantee that the user is who he claims to be.

Example how the response is created:

$userArray = [
  'timestamp' => "0.9696200 1503915319",
  'app_url' => 'http://...',
  'id' => "1",
  'char_name' => 'player',
  'race' => 'tryker',
  'cult' => 'neutral',
  'civ' => 'neutral',
  'organization' => 'marauder',
  'guild_id' => '105906000',
  'guild_icon' => '17',
  'guild_name' => 'guild',
  'grade' => 'Leader',
  'lang' => 'en'

$user = base64_encode(serialize($userArray));
$checksum = hash_hmac('sha1', $user, $appKey);

timestamp contains microseconds and seconds when the response was created and should be checked to prevent replaying the same response multiple times.
app_url must be checked to prevent same AppZone response to be used in other apps.

PHP interface


This function verifies AppZone user and checksum url parameters. Uses $_GET['user'] and $_GET['checksum'] directly.
Function returns boolean true if successful. $user variable will contain info from AppZone or an error message if there was an error

is set for future requests. PHP session is required.

Constants that should be defined :
secret key in AppZone
if empty, then user info is not verified (not recommended)


app url in AppZone
if empty, then automatic best guess url is tried
if false, then app url is not verified


max age in seconds for AppZone url to be valid
if 0, then timestamp is not verified
  require_once "ryzomapi_lite.php";

  define('RYAPI_AUTH_KEY', 'secret-key');
  define('RYAPI_APP_URL', 'http://app.url/');
  define('RYAPI_APP_MAXAGE', 30);


  $user = false;
  if (ryzom_app_authenticate($user)) {
    $charName = htmlspecialchars($user['char_name']);
    echo "Hello {$charName}!";
  } else {
    $error = htmlspecialchars($user);
    echo "Authentication failure ({$error}).";

In-game browser


Wiki implemetation

Pages in Category : "API templates" :

The code required to retrieve icons is raw html. You won't be able to format pictures as "easily" as when you use wiki code and the image is stored on Atys commons.



Complements to this page:

Last version 2022-05-24•