Documentation API
Namsor a développé une technologie d'analyse des noms qui offre une classification complète et précise. Notre API permet d'identifier : l'origine des noms, l'ethnicité, le pays de résidence, le genre et bien plus encore.
Cette solution prend en charge de nombreux alphabets* pour une couverture internationale optimale.
Introduction
À propos
- L'URL de base de l'endpoint est : https://v2.namsor.com/NamSorAPIv2
- Tous les endpoints nécessitent une clé API.
- Ne partagez jamais votre clé API avec PERSONNE.
Requêtes et réponses API
- Tous les endpoints retournent du JSON contenant soit un objet, soit un tableau d'objets imbriqué.
- Actuellement, certains endpoints de l'API NamSor utilisent des structures d'objets imbriqués dans leur corps de requête et/ou leurs réponses, veuillez vous référer à l'exemple de code correspondant.
- Soyez conscient que les données dans les exemples de code ont été encodées en URL dans les caractères ASCII correspondants si nécessaire, par exemple 谢晓亮 est remplacé par %E8%B0%A2%E6%99%93%E4%BA%AE. Les URLs ne peuvent pas contenir d'espaces ou de caractères non-ASCII. Lors de requêtes GET vers l'API, utilisez l'encodage URL pour convertir les caractères non-ASCII en un format qui peut être transmis sur internet.
Confidentialité des données
Par défaut, l'algorithme d'apprentissage automatique de Namsor peut améliorer l'évaluation des données basée sur les entrées de données et stocke les logs des requêtes soumises. Vous pouvez changer ces paramètres soit dans votre compte utilisateur, soit en appelant les endpoints API dédiés. Tous les logs de données sont sécurisés avec un chiffrement AES avant d'être stockés.
Si vous souhaitez désactiver l'apprentissage automatique basé sur vos soumissions, veuillez définir learnable sur false dans la section "Améliorer la confidentialité" sur la page mon compte. Lorsque défini sur false pour une clé API, les données traitées avec cette clé n'alimenteront pas l'algorithme d'apprentissage automatique.
Si vous souhaitez désactiver l'historique d'utilisation du service, veuillez définir anonymized sur true dans la section "Améliorer la confidentialité" sur la page mon compte. Lorsque défini sur true pour une clé API, les données traitées avec cette clé seront anonymisées de manière irréversible en utilisant le chiffrement SHA. Notez que le traitement intelligent pour les requêtes redondantes fonctionnera toujours même si vos données sont anonymisées.
Authentification
Création de clé API
Les comptes clients sont communs à tous les sites web du groupe Namsor. Pour créer une clé API, visitez Namsor ou un autre site du groupe Namsor et créez un compte. Naviguez vers la page d'informations du compte pour récupérer votre clé API. Votre compte nouvellement créé vient avec 1000 crédits gratuits que vous pouvez utiliser immédiatement avec n'importe lequel des outils de Namsor : API, processeur de fichiers CSV et Excel ou outils de développeur.
Installation de la clé API
Votre clé API doit être définie dans l'en-tête de votre requête en utilisant la propriété X-API-KEY. Veuillez vous référer aux exemples de code fournis pour l'installation correcte de la clé.
Vous devez remplacer your-api-key par votre clé API Namsor.
Crédits
Que sont les crédits
Nous utilisons un système de crédits pour suivre l'utilisation. Chaque plan vient avec une quantité mensuelle de crédits et un prix pour les requêtes qui dépassent votre allocation mensuelle. Le plan d'abonnement Basique gratuit vous accorde 1000 crédits mais d'autres plans sont disponibles au cas où vous avez des exigences plus élevées. Par exemple, avec 1000 crédits vous pouvez soit :
- Traiter 100 noms pour déterminer leurs origines.
- Traiter 50 noms pour déterminer leurs ethnicités.
- Traiter 100 noms pour déterminer leurs ethnicités de race US.
- Traiter 100 noms pour déterminer leurs pays de résidence.
- Traiter 1000 noms pour déterminer leurs genres.
Les routes d'administration sont gratuites.
Tolérance aux opérations répétées
Notre API dispose d'un traitement intelligent et ne facturera pas l'analyse de données identiques jusqu'à 20 fois. Par exemple, si vous soumettez le même nom complet 5 fois pour inférer son origine, vous ne serez facturé qu'1 crédit.
Limite souple vs limite stricte
Dans votre compte utilisateur, vous pouvez définir deux types de limites d'utilisation de crédits :
- Une limite souple qui déclenchera une notification par email lorsqu'elle sera atteinte.
- Une limite stricte qui déclenchera une notification par email et bloquera la clé API lorsqu'elle sera atteinte.
Suivre l'utilisation
Il y a deux façons de suivre votre utilisation de crédits : vérifiez les graphiques fournis dans votre compte utilisateur ou interrogez les routes d'administration appropriées (API Usage, API Usage History et API Usage History Aggregate).
Erreurs
L'API NamSor utilise les codes d'erreur suivants :
- 401Non autoriséClé API manquante ou incorrecte.
- 403InterditLimite API atteinte ou clé API désactivée.
- 404Non trouvéLa route spécifiée n'a pas pu être trouvée.
- 500Erreur interne du serveurErreur du serveur. Réessayez plus tard.
Explicabilité des résultats
L'API Namsor offre la possibilité d'obtenir une explication détaillée de la façon dont l'intelligence artificielle est arrivée à ses résultats pour une requête donnée. En activant cette option, un champ supplémentaire est inclus dans la réponse de l'API, fournissant une explication en code Python du processus suivi par l'IA.
Important
- Coût supplémentaire : L'activation de l'explicabilité entraîne un coût supplémentaire de 50 crédits par nom traité.
- Format d'explication : L'explication retournée est en code Python. Pour une utilisation optimale, il est recommandé de supprimer les tabulations et les retours à la ligne pour que le code soit utilisable.
Comment activer l'explicabilité :
- Contactez l'équipe Namsor : Avant d'utiliser cette fonctionnalité, veuillez contacter notre équipe pour activer l'option d'explicabilité sur votre compte client.
- Configurez la requête : Ajoutez l'en-tête suivant à votre requête API :
X-OPTION-EXPLANABILITY: true
X-OPTION-EXPLANABILITY: trueEn suivant ces étapes, chaque requête inclura maintenant une explication détaillée du résultat, vous permettant d'obtenir des insights approfondis sur le fonctionnement de notre intelligence artificielle spécialisée en onomastique.
Cas d'usage IA Act
L'API Namsor peut être instrumentale pour se conformer aux réglementations nationales ou supranationales visant à prévenir les résultats biaisés et les effets discriminatoires dans l'Intelligence Artificielle. Namsor est capable d'inférer des catégories spéciales de données personnelles à partir des noms pour estimer le risque de biais algorithmiques liés au genre, à la race, au contexte culturel/linguistique, à l'ethnicité ou au pays d'origine.
L'IA Act européen introduit une nouvelle exception concernant les "données sensibles" pour protéger les droits des citoyens contre la discrimination qui pourrait résulter de biais dans les systèmes d'IA. Dans le but d'assurer la détection et la correction des biais dans les systèmes d'IA à haut risque, il permet le traitement de catégories spéciales de données personnelles, comme une question d'intérêt public substantiel.
L'option d'explicabilité de Namsor est conçue pour fournir une formule mathématique fermée qui inclut l'explication complète de la classification des noms (avec à la fois les caractéristiques des données d'entraînement et les formules complètes du modèle). Cela peut être stocké à des fins d'audit dans les algorithmes d'IA de prise de décision.
Pour protéger la propriété intellectuelle de Namsor, nous exigeons une documentation spécifique et un accord de confidentialité signé avant d'activer cette option.