Welcome to the Ryzom API

Ryzom API is an URL based system to get some Ryzom information like game time, character, or guild profile.

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.

Changelog can be found on forums

PHP API

PHP API library can be found in ryzom api client repository.

3rd party libraries

(php) Sheet translations and info about resources can be found from https://github.com/nimetu/ryzom-extra repository.
json-resources branch has data in json format.

Time

To know the time and date in Ryzom.

Base URL

/time.php

URL Parameters

format
(optional), default 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.

PHP interface

ryzom_time_api()

Returns SimpleXMLElement or boolean false on failure.

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

Weather

To know the weather in Ryzom.

Base URL

/weather.php

URL Parameters

continent
(optional) comma separated continent names.
default: fyros,matis,tryker,zorai,nexus,sources,bagne,terre,route_gouffre,newbieland,kitiniere,matis_island
cycles
(optional) number between 0 to 40 of next cycles to include, default 4.
offset
(optional) number between 0 to 8 of previous cycles to include, default 0.
gametick
(optional), default current time.

PHP interface

ryzom_weather_api(string[] $contients, int $cycles, int $offset)

All parameters are optional and function can be called as ryzom_weather_api() to use API defaults.

<?php
  require_once "ryzomapi_lite.php";

  $weather = ryzom_weather_api(array('tryker'), 1);
  if ($weather !== false && !isset($weather['errors'])) {
    $currentCycle = $weather['cycle'];
    $currentWeather = $weather['continents']['tryker'][$currentCycle];
    $nextWeather = $weather['continents']['tryker'][$currentCycle+1];
    echo "Weather now: {$currentWeather['condition']}/{$currentWeather['value']}\n";
    echo "Weather next: {$nextWeather['condition']}/{$nextWeather['value']}\n";
  } else {
    echo "API failure\n";
    if (isset($weather['errors'])) {
      echo join("\n", $weather['errors'])."\n";
    }
  }

Returned JSON

{
    "version":"1.0",
    "hour":"1999944.241",
    "cycle":666648,
    "continents":{
        "tryker":{
            "666648":{
                "cycle":666648,
                "condition":"best",
                "value":"0.125",
                "text":"uiFair"
            }
        }
    }
}

Error can be detected with errors property being present.

{
    "version":"1.0",
    "errors":[
        "Invalid or missing continent parameter",
        "Offset must be between 0 and 8",
        "Cycles must be between 0 and 40"
    ]
}

Guilds list

Display 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

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

Character

Access character information.

Base URL

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

Guild

Access guild information.

Base URL

/guild.php?apikey=key

/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 return information for multiple guilds at once and so each <guild> elementy is 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.

PHP

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

Render

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

<?php
require_once "ryzomapi_lite.php";

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

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

Item icon

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

URL Description Default Excample 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.
iczahp_3.sitem
c (optional), default is 1
The color of the item. It's a value between 0 and 7
c=1
0 1 2 3
4 5 6 7
q (optional), default is 0
The quality of the item.
q=0
0 10
s (optional), default is 0
The size of the stack.
s=0
0 10
sap (optional) number of sap of the item.
-1 = (default) No sap icon, no number
0 = sap icon, no number
sap=-1
-1 0 1 2 3
destroyed (optional) display the item as if it was destroyed (with a red cross)
0 = (default)
destroyed=0
0 1
label (optional), draw icon text if present
1 = (default)
label=1
0 1
locked (optional) display the item as if it was locked by the owner
0 = (default)
locked=0
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.

<?php
require_once "ryzomapi_lite.php";

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

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

Guild icon

Base URL

/guild_icon.php?icon=:icon&size=:size

URL Parameters

icon
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.

<?php
require_once "ryzomapi_lite.php";

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

AppZone

User authentication for apps registered in AppZone

URL values

Because of php serialize, checksum must be validated before user value can be safely used.

Validating checksum will also give strong guarantee that user is who they claim to be.

Example how 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 response was created and should be checked to prevent replaying same response multiple times.

app_url must be checked to prevent same AppZone response to be used in other apps.

PHP interface

ryzom_app_authenticate(&$user)

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

$_SESSION['app.user'] is set for future requests. PHP session is required

Constants that should be defined

RYAPI_AUTH_KEY
secret key in AppZone
if empty, then user info is not verified (not recommended)
RYAPI_APP_URL
app url in AppZone
if empty, then automatic best guess url is tried
if false, then app url is not verified
RYAPI_APP_MAXAGE
max age in seconds for AppZone url to be valid
if 0, then timestamp is not verified 
<?php
  require_once "ryzomapi_lite.php";

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

  session_start();

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