Les champs retournés par l'API de conversion

Vous trouverez ici la description de chaque valeur retournée par l'API de conversion de textes. Le résultat est au format JSON. Comme pour tout langage structuré (XML, HTML...), vous n'avez pas besoin de coder votre propre parseur de JSON, le langage que vous utilisez propose forcément des fonctions ou librairies prêtes à l'emploi. En PHP par exemple, utilisez la fonction json_decode() pour transformer le flux textuel JSON en un array ou objet manipulable.

Structure de l'API JSON

Si vous vous voulez aller à l'essentiel, lisez les clés marquées [important].

metas
...api_version
...api_status [important]
...datetime_utc
error
...error_alias [important]
...error_message
options_set
...orig_language_id
...destin_language_id
...page_url
...repair_relative_links
...return_html_preview
...return_unknown_tags_list
...remove_unknown_tags
...prettify_json
converted_text [important]
html_preview
unknown_tags_list

api_version

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Exemple de valeur : 1.0

Affiche le numéro de version exact de l'API que vous avez appelée, sous la forme « [version majeure].[version mineure] ».

api_status

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Valeurs possibles : un des codes listés ci-dessous.

stable : cette version de l’API est la plus récente, elle est stable et peut être utilisée en production.
beta : future version de l’API, encore en phase de tests. Ne l’utilisez pas en production car sa stabilité n’est pas garantie et sa structure peut évoluer.
deprecated : cette version de l’API est obsolète, il en existe une version plus récente. L’ancienne reste disponible pour le moment, mais elle pourrait être retirée si des évolutions ultérieures la rendaient définitivement incompatible. Si vous utilisez cette version, il est recommandé de passer à la version stable la plus récente. Notez que nous privilégions les évolutions progressives et rétrocompatibles car une API digne de confiance se doit d'être stable sur la durée. Par ailleurs, les versions obsolètes seront maintenues autant que possible.

datetime_utc

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Exemple de valeur : 2017-08-14T21:38:31+00:00

Affiche la date à laquelle l'API a été générée, à l'heure UTC. UTC est le « temps universel », indépendant des fuseaux horaires, des changements d'heure hiver/été et de l'heure du pays qui héberge le site. A titre indicatif, voici les correspondances de l'UTC avec les heures quelques pays :
- France, Belgique : ajouter 1 heure en hiver ou 2 heures en été
- Pays-Bas : ajouter 1 heure
- Royaume-Uni : heure UTC
- États-Unis (ouest) : soustraire 5 heures
- États-Unis (est) : soustraire 8 heures

La date est rédigée au format standard ISO 8601 (ex : 2017-08-14T21:38:31+00:00). Des fonctions pour manipuler ce format de date existent dans tous les langages. En PHP par exemple, vous pouvez la convertir en timestamp avec la fonction strtotime() :

// Convertit la date UTC en timetamp UNIX (1502746711)
$timestamp = strtotime('2017-08-14T21:38:31+00:00');
// Convertit le timestamp en date française (14-08-2017 23h08)
echo date('d-m-Y H\hm', $timestamp);

error_alias

Type : chaîne de caractères
Niveau : 2 (dépend de error)
Valeurs possibles : un des codes d'erreurs listés ci-dessous.

Retourne un code indiquant la nature de l'erreur rencontrée, ou success si la conversion s'est bien réalisée. Ces codes d'erreurs sont invariables, vous pouvez les utiliser dans vos scripts pour identifier les erreurs et les traiter en conséquence.

success : la conversion s'est réalisée sans erreur.
unknown_call_options : un ou plusieurs paramètres que vous avez envoyés à l'API portent un nom inconnu. Les paramètres problématiques sont énumérés dans la clé error_message. Cette erreur est volontairement bloquante afin de vous permettre de repérer immédiatement d'éventuelles fautes de frappe dans vos paramètres. Sans cette sécurité, vous pourriez croire que vous avez activé un paramètre alors que, en réalité, il n'a pas été pris en compte.
undefined_text_to_convert : vous n'avez pas envoyé de texte à convertir via le paramètre text_to_convert.
empty_text_to_convert : le texte que vous tentez de convertir est vide (il ne contient aucun caractère ou n'est composé que de blancs). Vérifiez que ce cela n'est pas dû à un dysfonctionnement dans votre script (ex : texte perdu en cours de route). Si avez réellement besoin de gérer des textes vides, ajoutez une condition à votre script pour ne pas appeler l'API dans un tel cas et exécuter directement les actions que vous souhaitez.
page_not_found : vous avez fourni une URL en guise de texte à convertir, mais le contenu de la page n'a pas pu être récupéré car la page est introuvable (erreur 404). Vérifiez dans un navigateur que l'adresse est correcte.
cant_reach_url : vous avez fourni une URL en guise de texte à convertir, mais le contenu de la page n'a pas pu être récupéré pour une raison inconnue (hors erreur 404 car ce cas est déjà géré par l'erreur page_not_found).
undefined_orig_language_id : vous n'avez pas envoyé l'ID du langage du texte à convertir. Indiquez-le avec le paramètre orig_language_id.
undefined_destin_language_id : vous n'avez pas envoyé l'ID du langage dans lequel vous souhaitez convertir votre texte. Indiquez-le avec le paramètre destin_language_id.
unknown_orig_language_id : vous avez bien envoyé l'identifiant du langage d'origine du texte à convertir, mais ce numéro n'existe pas. Voir la documentation du paramètre orig_language_id.
unknown_destin_language_id : vous avez bien envoyé l'identifiant du langage dans lequel vous souhaitez convertir votre texte, mais ce numéro n'existe pas. Voir la documentation du paramètre destin_language_id.
missing_url_of_page : le texte à convertir contient des liens relatifs et vous n'avez pas indiqué l'URL de la page source via le paramètre page_url. Vous pouvez régler ce problème de deux façons :
- Soit en indiquant l'adresse de la page source via le paramètre page_url, afin de permettre la correction des liens relatifs en liens absolus ;
- Soit en ignorant l'erreur en définissant le paramètre repair_relative_links à FALSE. Les liens relatifs ne seront pas corrigés.
invalid_url_of_page : l'adresse que vous avez fournie dans le paramètre page_url n'est pas une URL valide.
fatal_error : une erreur imprévue s'est produite sur le serveur de conversion. Tentez à nouveau de convertir votre texte. Si le problème persiste, vous pouvez le signaler par le formulaire de contact.

error_message

Type : chaîne de caractères
Niveau : 2 (dépend de error)
Exemple de valeur : The URL you sent is invalid.

Affiche un court message décrivant l'erreur qui a été rencontrée, en fonction de la valeur de la clé error_alias. Si votre script ne prévoit pas de message pour certaines erreurs, vous pouvez afficher par défaut la valeur de cette clé à vos utilisateurs. Il sera plus explicite que la valeur de error_alias ou qu'un vague « erreur inattendue ».

N'utilisez pas cette clé pour détecter le type d'erreur rencontré. Pour cela, utilisez la valeur de la clé error_alias.

orig_language_id

Type : nombre entier (integer)
Niveau : 2 (dépend de options_set)
Exemple de valeur : 8

Affiche l'ID que vous avez indiqué comme langage d'origine, c'est-à-dire le langage avec lequel est balisé le texte que vous voulez convertir. Par exemple, si votre texte a été rédigé en Markdown et que vous voulez le convertir en HTML, le langage d'origine est le Markdown. Voir paramètres d'appel à l'API > orig_language_id.

destin_language_id

Type : nombre entier (integer)
Niveau : 2 (dépend de options_set)
Exemple de valeur : 12

Affiche l'ID que vous avez indiqué comme langage de destination, c'est-à-dire le langage vers lequel vous voulez convertir votre texte. Par exemple, si votre texte a été rédigé en Markdown et que vous voulez le convertir en HTML, le langage de destinationest le HTML. Voir paramètres d'appel à l'API > destin_language_id.

page_url

Type : chaîne de caractères
Niveau : 2 (dépend de options_set)
Exemple de valeur : https://domain.here/page.html

Affiche l'URL de la page source à convertir, si vous l'aviez fournie. Ce paramètre permet de transformer les éventuels liens relatifs contenus dans votre texte en liens absolus.