La Constitution d'ImmoState

• Introduction
• Fréquence de mise à jour
• Obtenir votre clé API
• API Bâtiments
• API Matériaux
• API Joueurs
• Volumes d'appels autorisés
• Utilisation communautaire et outils tiers
• Ce qui reste interdit

Une API (Interface de Programmation d'Application) est un outil qui permet à des programmes de communiquer entre eux de manière simple et efficace. Grâce à l'API que nous avons mise en place, vous pourrez récupérer des données automatiquement, sans avoir à tout faire manuellement. Cela vous permettra, par exemple, de créer des scripts pour traiter vos données de manière automatisée, ce qui vous fera gagner du temps dans vos stratégies sur le jeu.

Les données sont mises toutes les 4h, après la mise à jour du taux promoteur. Cela est normalement suffisant au regard des données partagées.

L'accès aux API nécessite une clé personnelle, propre à votre compte. Cette clé permet d'identifier vos appels et de vous garantir un accès stable, indépendamment des autres joueurs de votre foyer ou de votre réseau.

Vous pouvez générer votre clé depuis Options > API. Elle se présente sous la forme eiK8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Chaque appel à l'API doit inclure votre clé en paramètre :

• https://monde8.empireimmo.com/api/buildings.json?key=VOTRE_CLE
• https://monde8.empireimmo.com/api/materials.json?key=VOTRE_CLE
• https://monde8.empireimmo.com/api/players.json?key=VOTRE_CLE

Vous pouvez régénérer votre clé à tout moment depuis la même page. La régénération invalide immédiatement l'ancienne clé : pensez à mettre à jour vos scripts ou favoris en conséquence.

Ne partagez pas votre clé publiquement (dans un dépôt de code public, sur un salon Discord ouvert, etc.). Si votre clé a fuité, régénérez-la immédiatement.

L'API bâtiments vous donne la liste des bâtiments et leurs différentes données dans les formats suivants :

- Tous les bâtiments - JSON
- Bâtiments personnels - CSV
- Bâtiments entreprises - CSV
- Bâtiments terrains - CSV

Cette API comprend :

- Un nom
- Une description
- La liste des bâtiments "perso"
- La liste des bâtiments "entreprise"
- La liste des bâtiments "terrain"
- Date de mise à jour

Chaque bâtiment comprend :

- Un type
- Un nom
- Un niveau
- Une valeur
- Un loyer
- Une charge
- Un impôt
- Une promotion
- Un coût de construction
- Un coût d'embellissement
- Un coût de réparation

L'API matériaux vous donne la liste des matières premières et leurs usines de production dans les formats suivants :

- Liste des matériaux et usines - JSON
- Liste des matériaux - CSV
- Liste des usines - CSV

Cette API comprend :

- Un nom
- Une description
- La liste des matériaux
- La liste des usines
- Date de mise à jour

Chaque matière première comprend :

- Un nom
- Un prix
- Une unité

Chaque usine de production comprend :

- Une matière
- Un nom
- Une valeur
- Une charge
- Un impôt
- Une production

L'API joueurs vous donne la liste des joueurs dans les formats suivants :

- Liste des Joueurs - JSON
- Liste des Joueurs - CSV

Cette API comprend :

- Un nom
- Une description
- Le nombre de joueurs
- La liste des joueurs
- Le total des points des joueurs
- Date de mise à jour

Chaque joueur comprend :

- Un pseudo
- Des points
- Un classement
- Un niveau
- Une ville

Usage recommandé : 1 appel par API toutes les heures. C'est suffisant pour tous les usages constatés à ce jour.

Limite technique : au-delà de 6 appels par heure et par joueur, un système de limitation automatique (rate-limiting) peut bloquer temporairement l'accès. Cette limite offre une marge confortable pour un usage normal, y compris en cas de test ou de mise au point d'un script, tout en empêchant les appels en boucle (polling agressif, absence de cache, cron mal configuré).

Chaque réponse de l'API indique votre quota restant via les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset, pour vous permettre d'adapter votre script en conséquence. Au-delà de la limite, l'API renvoie une erreur (code 429) jusqu'à la réinitialisation de la fenêtre.

En cas de dépassement répété et manifestement volontaire de cette limite, votre clé API pourra être révoquée, dans les conditions prévues à la section Modération.

Cas particulier des outils partagés avec la communauté (voir section suivante) : si votre outil est utilisé par plusieurs joueurs, veillez à ce que ce soit votre serveur/backend qui interroge l'API une seule fois puis serve les données à vos utilisateurs (avec mise en cache), plutôt que de laisser chaque utilisateur de votre outil interroger l'API individuellement. Un outil à 50 utilisateurs qui génère 50 appels à chaque rafraîchissement serait considéré comme un abus, même si chaque utilisateur individuellement respecte la limite ci-dessus.

De plus en plus de joueurs développent leurs propres outils pour exploiter les données de l'API : calculateurs de rentabilité, tableaux de bord de filiale, scripts de suivi personnel, bots Discord de publication de résultats... C'est une excellente initiative que nous encourageons, à condition de respecter quelques règles simples.

Vous êtes libre d'utiliser votre clé API pour vos propres besoins (scripts, tableurs, applications privées), sans aucune démarche particulière, tant que vous respectez la fréquence de mise à jour indiquée ci-dessus et que vous mettez en cache les données récupérées plutôt que de les redemander en boucle.

Vous pouvez partager un outil que vous avez développé avec d'autres joueurs (via Discord, forum, ou tout autre canal communautaire), sans autorisation préalable de notre part, à condition que :

• l'outil reste gratuit, sans publicité ni monétisation d'aucune sorte ;
• vous indiquiez clairement, là où l'outil est visible, qu'il s'agit d'un outil non-officiel, développé par un joueur, et que les données affichées ne sont pas garanties par l'éditeur ;
• vous respectiez la fréquence d'appel indiquée plus haut (1 appel automatisé par heure, avec mise en cache).

Si vous envisagez de développer un outil monétisé (publicité, don, abonnement...) ou destiné à toucher un public large au-delà de la communauté du jeu (site public référencé, application mobile, etc.), contactez-nous au préalable via le Staff en précisant l'objet "API" dans votre message. Nous étudions chaque demande individuellement, dans l'intérêt du jeu et de sa communauté.

• Toute extraction automatisée des données du jeu en dehors de l'API officielle (scraping de pages, requêtes automatisées sur les tableaux du site, etc.) : seule l'API est autorisée pour la récupération automatisée de données.
• Toute utilisation d'une clé API autre que la vôtre, ou le partage de votre clé avec un tiers non autorisé.
• Toute sollicitation de l'API au-delà des volumes indiqués ci-dessus.
• Toute utilisation des données API dans le but de contourner les règles du jeu (multicompte, coordination frauduleuse, etc.) — voir la section Modération.

Le non-respect de ces règles peut entraîner la révocation de votre clé API, voire les sanctions prévues dans la section Modération.