API on Documentation Seurch

Authentification

Mon, 01 Jan 0001 00:00:00 +0000

Authentification#

Chaque requête API doit comporter une clé API valide. Les clés sont émises par utilisateur ; une requête sans clé reçoit 401, et une requête avec une clé incorrecte ou révoquée est rejetée.

L’API est une fonctionnalité auto-hébergée, donc les clés sont émises sur votre propre instance, pas sur le service hébergé seurch.eu.

Obtenir une clé#

Sur votre instance :

Dans l’interface web : Paramètres → Clés API, créez une clé (nommez-la optionnellement). La clé complète est affichée une seule fois ; copiez-la immédiatement.
Depuis la ligne de commande (administrateurs) : python manage.py create_api_key <nom_utilisateur> --name "mon script", voir Gestion des clés API.

Une clé ressemble à :

Limites de débit

Mon, 01 Jan 0001 00:00:00 +0000

Limites de débit#

Chaque clé API dispose de son propre budget, appliqué par deux limites qui s’appliquent ensemble. Une requête doit satisfaire les deux :

Limite	Par défaut	Rôle
Burst	`60/min`	Plafond à court terme, protège les fournisseurs amont d’un client incontrôlé.
Sustained	`5000/day`	Plafonne le volume quotidien total.

Sur une instance auto-hébergée, ces valeurs sont configurables avec API_THROTTLE_BURST et API_THROTTLE_SUSTAINED, voir Configuration.

Lorsque vous dépassez une limite#

Dépasser l’une ou l’autre limite renvoie :

Conventions

Mon, 01 Jan 0001 00:00:00 +0000

Conventions#

Paramètres de requête partagés#

Les points de terminaison de recherche acceptent un ensemble commun de paramètres. Chacun correspond à une option que le site web conserve dans son cookie de préférences ; ici, ils sont explicites dans l’URL.

Paramètre	S’applique à	Valeurs	Par défaut
`q`	tous les points de terminaison de recherche	La chaîne de requête (requise)	—
`engine`	web, images, actualités, vidéos, fiches	`brave`, `mojeek`, `marginalia`, ou `all` ; séparez-en plusieurs par une virgule ou un espace	`all`
`safe`	web, images, actualités, vidéos, fiches	`on` / `off` (`off`, `false`, `0`, `no` signifient tous off)	`on`
`lang`	la plupart des points de terminaison	Un code de langue, par ex. `fr`, `en`	vide (auto)
`page`	web, images, actualités, vidéos	Numéro de page, `1`–`50`	`1`
`date`	web, actualités, vidéos	Plage temporelle : `d` (jour), `w` (semaine), `m` (mois), `y` (année)	aucun

Notes :

Points de terminaison de recherche

Mon, 01 Jan 0001 00:00:00 +0000

Points de terminaison de recherche#

Les points de terminaison essentiels : recherche web, d’images, d’actualités et de vidéos, plus l’assistant « images similaires ». Tous acceptent les paramètres partagés (q, engine, safe, lang, page, date).

Recherche web#

GET /api/v1/web/?q=...

curl -H "Authorization: Api-Key seurch_sk_<préfixe>.<secret>" \
 "https://search.example.com/api/v1/web/?q=climat&engine=all&lang=fr&date=w"

{
 "query": "climat",
 "tab": "web",
 "page": 1,
 "engine": ["brave", "mojeek", "marginalia"],
 "correction": "",
 "results": [
 {
 "title": "Changement climatique",
 "url": "https://example.org/climat",
 "description": "...",
 "display_url": "example.org",
 "favicon_url": "https://...",
 "age": "il y a 2 jours",
 "source": "all",
 "source_label": "Brave, Mojeek, Marginalia",
 "sitelinks": []
 }
 ]
}

source / source_label — quels moteurs ont renvoyé le résultat. brave / mojeek / marginalia pour un seul moteur, ou both / all pour un accord inter-moteurs (source_label est la forme lisible).
correction — une correction orthographique suggérée, ou "".

Recherche d’images#

GET /api/v1/images/?q=...

{
 "query": "golden retriever",
 "tab": "images",
 "page": 1,
 "engine": ["brave"],
 "results": [
 {
 "title": "...",
 "url": "https://example.com/page",
 "source": "example.com",
 "thumbnail": "https://.../thumb.jpg"
 }
 ]
}

Images similaires#

Reproduit la grille « images similaires » de la lightbox du site web, une recherche d’images alimentée par la légende d’une image ouverte.

Cartes

Mon, 01 Jan 0001 00:00:00 +0000

Cartes#

Géocodez un nom de lieu ou effectuez un géocodage inverse d’une paire de coordonnées, en utilisant Nominatim d’OpenStreetMap. Aucune clé de fournisseur n’est requise.

GET /api/v1/maps/

Géocoder un nom de lieu#

GET /api/v1/maps/?q=<lieu>&limit=<n>&lang=<code>

q — le lieu ou l’adresse à rechercher (requis dans ce mode).
limit — nombre maximum de résultats, 1–50 (par défaut 10).
lang — langue préférée pour les noms.

curl -H "Authorization: Api-Key seurch_sk_<préfixe>.<secret>" \
 "https://search.example.com/api/v1/maps/?q=Tour+Eiffel&limit=1"

{
 "query": "Tour Eiffel",
 "places": [
 {
 "name": "Tour Eiffel",
 "display_name": "Tour Eiffel, Paris, France",
 "lat": 48.8584,
 "lon": 2.2945,
 "category": "tourism",
 "type": "attraction",
 "addresstype": "tourism",
 "importance": 0.82,
 "embed_url": "https://www.openstreetmap.org/export/embed.html?...",
 "mini_embed_url": "https://...",
 "osm_url": "https://www.openstreetmap.org/...",
 "directions_url": "https://www.openstreetmap.org/directions?...",
 "geo_uri": "geo:48.8584,2.2945"
 }
 ]
}

Géocodage inverse de coordonnées#

Passez lat et lon à la place de q :

Traduction

Mon, 01 Jan 0001 00:00:00 +0000

Traduction#

Traduisez du texte entre langues, alimenté par le LibreTranslate de l’instance. Ce point de terminaison accepte GET ou POST ; utilisez POST pour garder le texte long hors de l’URL et des journaux.

GET /api/v1/translate/
POST /api/v1/translate/

Traduire du texte#

Paramètre	Requis	Signification
`q` (ou `text`)	oui	Le texte à traduire
`target`	oui	Code de la langue cible (par ex. `fr`)
`source`	non	Code de la langue source ; par défaut `auto` (détection automatique)

# GET
curl -H "Authorization: Api-Key seurch_sk_<préfixe>.<secret>" \
 "https://search.example.com/api/v1/translate/?q=hello&target=fr"

# POST (mieux pour les textes longs)
curl -X POST -H "Authorization: Api-Key seurch_sk_<préfixe>.<secret>" \
 -d "q=hello world" -d "target=fr" \
 "https://search.example.com/api/v1/translate/"

{
 "source": "auto",
 "target": "fr",
 "translated_text": "bonjour le monde",
 "detected_lang": "en"
}

detected_lang n’est renseigné que lorsque source était auto (sinon vide).
Si la traduction n’est pas configurée sur l’instance, le point de terminaison renvoie 503 avec {"detail": "Translation is unavailable or not configured on this deployment."}.

Lister les langues disponibles#

GET /api/v1/translate/languages/

{
 "languages": [
 { "code": "en", "name": "English" },
 { "code": "fr", "name": "French" }
 ]
}

La liste reflète ce que l’instance LibreTranslate connectée propose ; voir Traduction pour le côté auto-hébergement.

Instantané et fiches

Mon, 01 Jan 0001 00:00:00 +0000

Réponses instantanées et fiches de connaissance#

Ces deux points de terminaison reproduisent les réponses en ligne et les panneaux latéraux du site web. Leur contenu variant selon le type de réponse et le fournisseur, ils renvoient du JSON de forme fournisseur plutôt qu’un schéma fixe par champ ; traitez les structures comme des données et lisez les champs dont vous avez besoin.

Réponses instantanées#

GET /api/v1/instant/?q=...

Renvoie la réponse instantanée pour une requête utilitaire (calculs, conversion d’unités/base/couleur, météo, devise, horloge mondiale, hachages, QR, « quelle est mon IP », …), ou null lorsque la requête n’est pas une réponse inline de Seurch.

Points de terminaison méta

Mon, 01 Jan 0001 00:00:00 +0000

Points de terminaison méta#

Assistants pour la complétion automatique, l’état de santé des fournisseurs, l’introspection de clé et la découverte de points de terminaison. La racine, status/ et key/ ne comptent pas dans votre usage mensuel de recherches (ils comptent quand même contre la limite de débit brute).

Suggestions#

Suggestions de complétion automatique de la barre de recherche pour une requête. (Compte comme une recherche.)

GET /api/v1/suggest/?q=...

curl -H "Authorization: Api-Key seurch_sk_<préfixe>.<secret>" \
 "https://search.example.com/api/v1/suggest/?q=clim"

{
 "query": "clim",
 "suggestions": ["climat", "changement climatique", "escalade"]
}

Statut des fournisseurs#

État actuel (opérationnel/hors service) de chaque fournisseur amont configuré, les données derrière la page /status. (Ne compte pas dans l’usage.)

Erreurs

Mon, 01 Jan 0001 00:00:00 +0000

Erreurs#

L’API utilise des codes de statut HTTP standard et renvoie un corps JSON décrivant le problème.

Codes de statut#

Code	Signification	Cause typique
`200`	OK	Requête réussie.
`400`	Mauvaise requête	Un paramètre incorrect, par ex. un `q` manquant, un `page` non entier, ou un `engine` inconnu.
`401`	Non autorisé	Aucune clé API envoyée (ou aucun en-tête d’authentification reconnu).
`403`	Interdit	La clé appartient à un compte désactivé.
`429`	Trop de requêtes	Une limite de débit a été dépassée.
`503`	Service indisponible	Un service dépendant n’est pas configuré, par ex. la traduction lorsque LibreTranslate n’est pas défini.

Corps d’erreur#

Erreurs de validation (`400`)#

Messages indexés par champ :

API on Documentation Seurch

Authentification

Authentification#

Obtenir une clé#

Limites de débit

Limites de débit#

Lorsque vous dépassez une limite#

Conventions

Conventions#

Paramètres de requête partagés#

Points de terminaison de recherche

Points de terminaison de recherche#

Recherche web#

Recherche d’images#

Images similaires#

Cartes

Cartes#

Géocoder un nom de lieu#

Géocodage inverse de coordonnées#

Traduction

Traduction#

Traduire du texte#

Lister les langues disponibles#

Instantané et fiches

Réponses instantanées et fiches de connaissance#

Réponses instantanées#

Points de terminaison méta

Points de terminaison méta#

Suggestions#

Statut des fournisseurs#

Erreurs

Erreurs#

Codes de statut#

Corps d’erreur#

Erreurs de validation (400)#

Erreurs de validation (`400`)#