Obtenir les clés API#

Guides pas à pas pour obtenir la clé de chaque fournisseur. Aucune n’est requise pour démarrer Seurch, mais au moins un moteur web (Brave est le plus simple) est nécessaire pour des résultats utiles. Chaque fournisseur que vous ignorez masque simplement son onglet ou sa fiche ; voir Fournisseurs de recherche pour ce que chacun active.

Une fois que vous avez une clé, définissez la variable d’environnement correspondante (voir Configuration) et redémarrez l’application.

La plupart de ces fournisseurs ont un niveau gratuit suffisamment généreux pour une instance personnelle ou pour une petite équipe ; Seurch met agressivement en cache et n’appelle les API de fiches payantes que lorsqu’une requête correspond réellement. Les clés partagées (public pour Marginalia, Stack Exchange anonyme) ne nécessitent aucune inscription. TheTVDB fait exception : il n’a pas de niveau gratuit et exige soit une licence commerciale, soit une clé financée par les utilisateurs accompagnée d’un code PIN d’abonné.

Brave Search — BRAVE_API_KEY#

Alimente les onglets Web, Images, Actualités et Vidéos depuis une seule clé. C’est le fournisseur à configurer en premier.

1. Rendez-vous sur le site Brave Search API et créez un compte sur le tableau de bord API.
2. Ajoutez le plan Data for Search et choisissez le niveau Gratuit (il demande une carte bancaire pour vérification, mais le niveau gratuit n’est pas facturé).
3. Ouvrez Clés API dans le tableau de bord et générez une clé.
4. Copiez-la dans BRAVE_API_KEY.

Brave Suggest (complétion automatique) — BRAVE_SUGGEST_API_KEY#

Active la complétion automatique dans la barre de recherche. C’est un abonnement séparé de la clé de recherche ci-dessus, avec sa propre clé.

1. Dans le même tableau de bord Brave API, abonnez-vous au plan Autosuggest (niveau gratuit disponible).
2. Générez une clé pour cet abonnement.
3. Copiez-la dans BRAVE_SUGGEST_API_KEY.

Laissez-la non définie pour fonctionner sans complétion automatique ; tout le reste fonctionne quand même.

Mojeek — MOJEEK_API_KEY#

Ajoute l’index web indépendant Mojeek à l’onglet Web.

1. Visitez la page Mojeek Search API et demandez l’accès à l’API (un niveau gratuit est disponible).
2. Une fois approuvé, copiez la clé qu’ils émettent.
3. Définissez-la comme MOJEEK_API_KEY.

Marginalia — MARGINALIA_API_KEY#

Ajoute l’index Marginalia non commercial et axé sur le petit web. Aucune inscription requise.

• La valeur littérale public est une clé partagée gratuite et est la valeur par défaut dans .env.example, limitée à environ 1 requête toutes les 5 secondes.
• Pour un quota plus élevé et non partagé, demandez une clé personnelle sur la page API Marginalia.

MARGINALIA_API_KEY=public   # fonctionne d'emblée

Staan — STAAN_API_KEY#

Ajoute Staan à l’onglet Web, l’index web européen construit par European Search Perspective (la coentreprise de Qwant et Ecosia). Résultats web uniquement.

1. Inscrivez-vous sur staan.ai.
2. Créez une clé API depuis votre tableau de bord.
3. Renseignez-la dans STAAN_API_KEY.

Le quota est de 1 000 requêtes gratuites par mois, puis à partir de 1 EUR pour 1 000.

L’API de Staan plafonne la pagination à un décalage de 30 : Staan alimente donc les quatre premières pages d’une recherche puis se retire. Elle refuse également les requêtes de plus de 400 caractères. Dans les deux cas les autres moteurs répondent toujours, la page n’est donc jamais vide.

Pixabay (images) — PIXABAY_API_KEY#

Mélange des images Pixabay libres de droits dans l’onglet Images.

1. Créez un compte gratuit sur Pixabay.
2. Une fois connecté, ouvrez la documentation API Pixabay ; votre clé API personnelle s’affiche en haut de cette page.
3. Copiez-la dans PIXABAY_API_KEY.

World News API (actualités) — WORLDNEWS_API_KEY#

Mélange des articles de l’API World News dans l’onglet Actualités.

1. Inscrivez-vous sur worldnewsapi.com (le plan gratuit accorde une allocation journalière de points).
2. Ouvrez votre tableau de bord de compte et copiez la clé API.
3. Définissez-la comme WORLDNEWS_API_KEY.

TheTVDB (fiche film / série) — THETVDB_API_KEY#

Active la fiche de connaissance film / série.

1. Créez un compte sur TheTVDB et ouvrez votre tableau de bord des clés API.
2. TheTVDB propose deux licences pour son API ; choisissez celle sous laquelle votre instance est réellement licenciée :
   • une licence négociée / commerciale, qui ne demande que la clé, ou
   • une clé financée par les utilisateurs, qui exige en plus le code PIN d’abonné TheTVDB de l’utilisateur final.
3. Copiez la clé dans THETVDB_API_KEY et, pour une clé financée par les utilisateurs, le code PIN d’abonné dans THETVDB_PIN (laissez-le vide pour une clé licenciée).

L’attribution est affichée sur la fiche, comme l’exigent les conditions de TheTVDB.

TripAdvisor (fiche lieux) — TRIPADVISOR_API_KEY#

Active la fiche restaurant / hôtel / attraction.

1. Inscrivez-vous à la TripAdvisor Terra Partner API.
2. Dans le portail développeur, créez une clé API pour le forfait de votre compte.
3. Copiez-la dans TRIPADVISOR_API_KEY. Seurch l’envoie dans l’en-tête X-API-Key.

L’ancienne API Content est retirée du service. Les clés émises pour api.content.tripadvisor.com renvoient désormais 403. Si votre fiche lieux a cessé d’apparaître, c’est la raison : obtenez une clé Terra et remplacez la valeur.

La fiche est construite à partir des points de terminaison catalogue de Terra, qui répondent sans liste d’autorisation partenaire ni restriction géographique. Cette projection est réduite : la fiche affiche donc le nom de l’établissement, sa zone, son adresse, sa note, son nombre d’avis, une description et un lien, et pas de photo, de cuisine, de niveau de prix ni de classement, qui ne sont servis que pour les établissements sous licence individuelle d’un partenaire.

Les conditions de TripAdvisor exigent d’afficher les attributions TripAdvisor là où ses données apparaissent, ce que la fiche de Seurch fait déjà, et que les pages portant son contenu soient tenues hors des index des moteurs de recherche, ce que Seurch fait en marquant noindex toute page de résultats affichant la fiche. Vous pouvez également restreindre la clé à l’IP de votre serveur dans leur portail.

Stack Exchange (fiche Q&A) — STACKEXCHANGE_API_KEY#

Active la fiche de questions-réponses Stack Exchange. Une clé est optionnelle.

• Sans clé, Seurch utilise le quota partagé anonyme (10 000 requêtes/jour partagées entre tous les appelants anonymes), ce qui convient pour un faible trafic.

• Avec une clé, vous obtenez un quota dédié beaucoup plus élevé :

  1. Enregistrez une application sur Stack Apps → Register OAuth (utilisez l’URL de votre instance ; vous n’avez pas besoin du flux OAuth).
  2. Copiez la Clé générée.
  3. Définissez-la comme STACKEXCHANGE_API_KEY.

Fournisseurs ne nécessitant aucune clé#

Ceux-ci fonctionnent d’emblée, sans compte ni clé :

L’onglet Traduction est la seule fonctionnalité sans clé qui nécessite quand même une infrastructure : une instance LibreTranslate vers laquelle vous pointez Seurch, voir Traduction.

Après avoir ajouté les clés#

1. Placez chaque valeur dans votre environnement (ou .env), voir Configuration.
2. Redémarrez l’application pour qu’elle prenne en compte les nouvelles variables.
3. Vérifiez la page /status (ou le point de terminaison API status/) pour confirmer que chaque fournisseur rapporte un état sain.