API — documentation

API de la calculatrice

Le même moteur que la calculatrice en ligne, appelable depuis n'importe quel langage. Un appel, un résultat : envoyez une expression, recevez la valeur calculée.

Pour essayer sans coder : la calculatrice en ligne

Point d'entrée

POST https://pemdasai.com/api/public/calc
  • Méthode : POST uniquement. Corps : JSON. Réponse : JSON.
  • CORS ouvert : appelable depuis une page web hébergée ailleurs, comme depuis un script ou un terminal.

Authentification

Chaque appel doit être signé avec votre clé personnelle, formaté pk_ suivi de 48 caractères hexadécimaux. Passez-la dans l'un des deux en-têtes :

Authorization: Bearer pk_VOTRE_CLE
x-api-key: pk_VOTRE_CLE

Créer ma clé d'accès (connexion requise). Une clé supprimée cesse de fonctionner immédiatement, et les appels ne fonctionnent plus sans clé.

Paramètres du corps de requête

NomTypeObligatoireDescription
exprchaîneobligatoire si exprs est absentExpression à calculer, de 1 à 2 000 caractères. Syntaxe complète de la calculatrice : opérateurs + − × ÷ % ^ **, fonctions (sin, cos, sqrt, ln, max, min…), constantes (pi, e, phi), factorielle ! et variables.
exprstableau de chaînesobligatoire si expr est absent1 à 100 expressions, calculées en un seul appel avec le même scope. La réponse contient un tableau « results » dans le même ordre.
scopeobjetoptionnelValeurs des variables : nom en lettres, chiffres ou _ (max 32 caractères, ne commence pas par un chiffre), valeur numérique finie. Exemple : {"x": 4, "y": 2.5}. Les variables absentes valent 0.

Exemple de corps complet : {"expr": "2 + 3 * x", "scope": {"x": 4}} — soit un calcul simple, soit un lot via « exprs », jamais les deux.

Réponses en cas de succès — 200

Calcul simple :

{"result": 14}

Lot d'expressions :

{"results": [5, 8, 4]}

Chaque réponse succès et erreur porte un en-tête « x-ratelimit-remaining » : le nombre d'appels restants dans la minute en cours. Les résultats infinis (inf) ou indéfinis (nan) sont renvoyés sous forme de chaînes, car JSON ne les représente pas.

Réponses d'erreur

401En-tête d'authentification absent, ou clé inconnue ou supprimée.

{"error": "Clé d'accès manquante ou invalide. Créez-en une sur pemdasai.com/cles-api."}

400Corps JSON illisible, ou « expr » et « exprs » absents tous les deux ou fournis ensemble.

{"error": "Corps JSON invalide."}

422Expression syntaxiquement invalide, variable interdite ou erreur de calcul (division par zéro, factorielle négative…).

{"error": "Fin d'expression inattendue (position 4)"}

429Plus de 60 requêtes envoyées dans la même minute avec la même clé.

{"error": "Trop de requêtes", "retryAfter": 12}

En-tête : retry-after: 12

Toute erreur de calcul renvoie un corps {"error": "…"} expliquant le problème et la position du caractère fautif dans l'expression.

Limite d'usage

  • 60 requêtes par minute, comptées par clé d'accès. Le lot « exprs » compte pour une requête, quel que soit son nombre d'expressions.
  • Au-delà, réponse 429 avec « retryAfter » (secondes à attendre) et en-tête « retry-after ». Lisez « x-ratelimit-remaining » pour ralentir avant d'être bloqué.

Exemples complets

import requests

API_URL = "https://pemdasai.com/api/public/calc"
HEADERS = {"Authorization": "Bearer pk_VOTRE_CLE"}

# Un calcul simple, avec une variable
r = requests.post(API_URL, headers=HEADERS,
                  json={"expr": "2 + 3 * x", "scope": {"x": 4}})
print(r.json())   # {"result": 14}
# Calculs restants dans la minute :
print(r.headers.get("x-ratelimit-remaining"))   # 59

# Plusieurs expressions en un seul appel (100 max)
r = requests.post(API_URL, headers=HEADERS,
                  json={"exprs": ["x + 1", "x * 2", "sqrt(x^2)"],
                        "scope": {"x": 4}})
print(r.json())   # {"results": [5, 8, 4]}

Gestion des erreurs :

r = requests.post(API_URL, headers=HEADERS, json={"expr": "1 /"})
if r.status_code == 200:
    print(r.json()["result"])
else:
    print(r.status_code, r.json()["error"])
    # 422 Fin d'expression inattendue (position 4)

# Quota dépassé : réessayez après « retryAfter » secondes
if r.status_code == 429:
    print("Nouvel essai dans", r.json()["retryAfter"], "s")

Notes importantes

  • « log » est le logarithme naturel (ln en Python) ; « log10 » est la base 10. « % » est le reste de division, pas un pourcentage.
  • Les expressions acceptent aussi × et ÷, et ** comme puissance (comme Python) ; ^ est également accepté.
  • La liste complète des fonctions et constantes est décrite sur la page calculatrice. Le même moteur tourne côté serveur, sans état entre les appels.
  • Tenez votre clé secrète : ne la mettez jamais dans un dépôt de code public ou une page web visible.

Une question sur l'API ? Utilisez la page contact — le support répond dans la journée.