Εθνικότητα από ένα όνομα: τι μπορεί και τι δεν μπορεί να σου πει ένα όνομα
Μία κλήση API μετατρέπει ένα μικρό όνομα ή επώνυμο σε ταξινομημένη λίστα των χωρών από τις οποίες προέρχεται, με μια πιθανότητα σε καθεμία. Απαντά σε ένα ερώτημα για το όνομα — που είναι άλλο ερώτημα από το πού ζει το πρόσωπο, και άλλο ακόμη από το ποιος είναι.
Η σύντομη απάντηση
- Παίρνεις μια ταξινομημένη λίστα με έως 25 χώρες, κάθε μία με πιθανότητα, κωδικό ISO, όνομα χώρας και, όπου η χώρα τα έχει καταγεγραμμένα, την ηπειρωτική και στατιστική της περιοχή.
- Η ίδια απάντηση περιέχει επίσης το φύλο, τη γλώσσα προέλευσης, τη σημασία του ονόματος και την κατανομή του στις εθνοτικές ομάδες, από μια βάση δεδομένων που καλύπτει 192 χώρες.
- Κοστίζει 2 credits ανά όνομα — διπλάσιο από μια απλή αναγνώριση φύλου, γιατί είναι βαρύτερο ερώτημα. Τα credits αγοράζονται προκαταβολικά και δεν λήγουν.
- Είναι στατιστική για το όνομα, όχι ισχυρισμός για το πρόσωπο. Χρησιμοποίησέ το για προσφωνήσεις, συγκεντρωτική ανάλυση και ποιότητα δεδομένων — όχι για να αποφασίσεις κάτι για έναν συγκεκριμένο άνθρωπο.
Από πού προέρχεται ο αριθμός;
Εδώ δεν μαντεύει κανένα μοντέλο, και τίποτα δεν παράγεται. Η πιθανότητα είναι αριθμητική πάνω σε εγγραφές που πραγματικά έχουμε — γι' αυτό το ίδιο όνομα επιστρέφει την ίδια λίστα σήμερα, τον επόμενο μήνα και τον επόμενο χρόνο.
Μπαίνουν δύο σήματα. Το πρώτο είναι πώς κατανέμονται οι εγγραφές του ονόματος στις χώρες — ένα όνομα που έχουμε κυρίως από την Πολωνία γέρνει προς τα πολωνικά. Το δεύτερο είναι πόσο μεγάλος είναι ο κάθε πληθυσμός, που εμποδίζει μια μικρή χώρα με καλά τεκμηριωμένο όνομα να προσπεράσει μια μεγάλη μόνο χάρη στον όγκο. Τα δύο μέσοσταθμίζονται ανά χώρα, ό,τι είναι κάτω από ένα τοις εκατό απορρίπτεται, και ό,τι μένει ταξινομείται.
Επειδή είναι κατανομή, ένα όνομα συνηθισμένο σε δύο χώρες απαντά με δύο χώρες αντί να διαλέξει νικητή. Ακριβώς αυτό είναι το χρήσιμο: το σχήμα της λίστας σου λέει πόσο μπορείς να εμπιστευτείς την πρώτη καταχώριση.
Τι επιστρέφει
Ένα POST, ένα όνομα, μία απάντηση. Η λίστα παρακάτω είναι συντομευμένη· η πραγματική φτάνει στις 25 πιθανότερες χώρες.
POST https://gender-api.com/v2/country-of-origin
{ "first_name": "Johann" }{
"result_found": true,
"first_name": "Johann",
"gender": "male",
"probability": 0.9,
"language_of_origin": "Germanic",
"meaning": "…",
"country_of_origin": [
{
"country_name": "Germany",
"country": "DE",
"probability": 0.52,
"continental_region": "Europe",
"statistical_region": "Western Europe"
},
{
"country_name": "Austria",
"country": "AT",
"probability": 0.48,
"continental_region": "Europe",
"statistical_region": "Western Europe"
}
],
"ethnicity": {
"id": "GERMANIC",
"name": "Germanic (German, Austrian, Swiss)",
"distribution": [ … ]
},
"details": { "credits_used": 2, "samples": 890, "duration": "414ms" }
}Πρόσεξε τα δύο πεδία που κάνουν την απάντηση ελέγξιμη: το samples σου λέει σε πόσες εγγραφές στηρίζεται, και το credits_used επιβεβαιώνει τα δύο credits. Μια απάντηση με λίγα samples δεν σου κρύβεται.
- Με τα continental_region και statistical_region μπορείς να συγκεντρώσεις τη λίστα σε περιοχές χωρίς να συντηρείς δική σου αντιστοίχιση.
- Η απάντηση περιέχει επίσης έναν σύνδεσμο προς έναν διαδραστικό χάρτη του ονόματος — ο γρηγορότερος τρόπος να ελέγξεις ένα αποτέλεσμα με το μάτι.
- Κάθε πεδίο τεκμηριώνεται στην τεκμηρίωση v2.
Η προέλευση δεν είναι ο τόπος διαμονής
Αυτή είναι η πιο συχνή παρανόηση, και συμβαίνει και προς τις δύο κατευθύνσεις. Δύο διαφορετικά πεδία, δύο διαφορετικές σημασίες, αντίθετες κατευθύνσεις.
| Ερώτηση | Η χώρα που στέλνεις | Η χώρα που παίρνεις πίσω |
|---|---|---|
| Πεδίο | country, locale, ip |
country_of_origin |
| Σημαίνει | Πού βρίσκεται το πρόσωπο τώρα | Από πού προέρχεται το όνομα |
| Αλλάζει την απάντηση για το φύλο | Ναι — το Andrea είναι αρσενικό στην Ιταλία και θηλυκό στη Γερμανία | Όχι — είναι έξοδος, όχι είσοδος |
| Συνήθως το ξέρεις ήδη | Ναι — από τη διεύθυνση αποστολής, το domain ή την IP | Όχι — αυτό είναι ακριβώς που αγοράζεις |
| Credits | Δωρεάν — μια παράμετρος, όχι ερώτημα | 2 ανά όνομα |
Τι δεν είναι
Ένα όνομα είναι τεκμήριο για ένα όνομα. Το να το αντιμετωπίζεις ως τεκμήριο για ένα πρόσωπο είναι το σημείο όπου αυτού του τύπου τα δεδομένα πάνε λάθος, οπότε αξίζει να είμαστε ξεκάθαροι για τα όρια πριν χτίσεις πάνω τους.
Ένα πρόσωπο με το όνομα Nguyen μπορεί να γεννήθηκε στη Μελβούρνη, και ένα πρόσωπο με το όνομα Smith μπορεί να μην πάτησε ποτέ το πόδι του σε αγγλόφωνη χώρα. Το endpoint απαντά στο «από πού προέρχεται αυτό το όνομα», και αυτό είναι το μόνο ερώτημα στο οποίο απαντά.
- Δεν είναι εθνικότητα, ούτε ιθαγένεια, ούτε τόπος γέννησης — και δεν αποδεικνύει κανένα από τα τρία.
- Δεν είναι η εθνοτική ταυτότητα του προσώπου. Η εθνοτική κατανομή περιγράφει πώς το όνομα εξαπλώνεται στις ομάδες: μια ιδιότητα του ονόματος.
- Δεν πρέπει να αποφασίζει τίποτα για ένα συγκεκριμένο πρόσωπο — ούτε τιμή, ούτε αίτηση, ούτε βαθμολογία κινδύνου. Τα δεδομένα που δείχνουν εθνοτική προέλευση είναι ειδική κατηγορία κατά το άρθρο 9 του GDPR, και αυτή η απόφαση είναι δική σου ως υπεύθυνου επεξεργασίας, όχι δική μας.
- Δεν είναι εικασία. Όπου έχουμε πολύ λίγα, το result_found είναι false και το πλήθος των samples το λέει — αντί να επινοηθεί μια εύλογη χώρα για να συμπληρωθεί το πεδίο.
Από τη δική μας πλευρά: είμαστε γερμανική εταιρεία, όλοι οι διακομιστές βρίσκονται στη Γερμανία, τα δεδομένα επεξεργάζονται εντός ΕΕ, και σύμβαση επεξεργασίας δεδομένων μπορείς να ζητήσεις από τον λογαριασμό σου. Η πλήρης εικόνα βρίσκεται στην επισκόπηση απορρήτου.
Σε τι χρησιμεύει στην πράξη
- Να πετύχεις τη σωστή προσφώνηση. Το να ξέρεις ότι ένα όνομα είναι ιταλικό και όχι γερμανικό είναι αυτό που μετατρέπει το «Andrea» από λάθος χαιρετισμό σε σωστό — και η αναγνώριση φύλου στην ίδια απάντηση είναι το μέρος που το εφαρμόζει.
- Ανάλυση αγοράς και κοινού σε συγκεντρωτικό επίπεδο. Σε ποια γλώσσα να μεταφράσεις μια καμπάνια, ποιες περιοχές φτάνει πραγματικά μια λίστα αλληλογραφίας, πού μεγάλωσε μια πελατειακή βάση.
- Ποιότητα δεδομένων. Μια λίστα όπου η κατανομή προέλευσης αλλάζει ξαφνικά σχήμα σημαίνει συνήθως ότι μια εισαγωγή πήγε λάθος, όχι ότι το κοινό μετακόμισε.
- Έρευνα και δημογραφία, όπου μια κατανομή σε επίπεδο ονόματος για μια ολόκληρη κοόρτη είναι η μονάδα ανάλυσης και δεν βγαίνει κανένα συμπέρασμα για μεμονωμένα πρόσωπα.
- Μεταγραφή και αντιστοίχιση, όπου η γνώση της πιθανής προέλευσης ενός ονόματος περιορίζει τις εύλογες γραφές του.
Να το τρέξεις σε μια λίστα
Η μορφή batch παίρνει έως 100 ονόματα ανά αίτημα, χωρίς όριο στον αριθμό των αιτημάτων. Το payload είναι ένας απλός πίνακας JSON.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Αντί για μικρό όνομα λειτουργεί και ένα πλήρες όνομα ή μια διεύθυνση e-mail — πρώτα εξάγεται το όνομα, μετά επιλύεται η προέλευση.
- Επίσημοι clients για PHP, Python, Node, Java, Go, Ruby, Rust, Perl και .NET.
- Για μια εφάπαξ λίστα και όχι για ολοκλήρωση, δες μαζική αναγνώριση φύλου — τα ίδια credits, χωρίς κώδικα.
- Κάθε πεδίο, κάθε σφάλμα και μια περιγραφή OpenAPI: η τεκμηρίωση v2.
Συχνές ερωτήσεις
Μπορείς να βρεις την εθνικότητα κάποιου από το όνομά του;
Όχι, και καμία έντιμη υπηρεσία δεν μπορεί. Αυτό που παίρνεις είναι πού εμφανίζεται το όνομα και πόσο έντονα, ταξινομημένο κατά χώρα — μια στατιστική για το όνομα, όχι ένα γεγονός για το πρόσωπο που το φέρει. Πολλοί άνθρωποι φέρουν ένα όνομα του οποίου η προέλευση δεν έχει καμία σχέση με τον τόπο γέννησής τους.
Τι επιστρέφει το endpoint;
Μια ταξινομημένη λίστα με έως 25 χώρες, κάθε μία με πιθανότητα, κωδικό χώρας ISO, όνομα χώρας και — όπου η χώρα τα έχει καταγεγραμμένα — την ηπειρωτική και στατιστική της περιοχή. Η ίδια απάντηση περιέχει επίσης το φύλο, τη γλώσσα προέλευσης, τη σημασία του ονόματος και την κατανομή του στις εθνοτικές ομάδες.
Πώς υπολογίζεται η πιθανότητα;
Από δύο σήματα: ποιο ποσοστό των εγγραφών που έχουμε για το όνομα προέρχεται από κάθε χώρα, και πόσο μεγάλος είναι ο κάθε πληθυσμός. Τα δύο μέσοσταθμίζονται ανά χώρα, οι χώρες στο ένα τοις εκατό ή κάτω απορρίπτονται, και τα υπόλοιπα ταξινομούνται. Κάθε τιμή είναι μερίδιο του συνόλου και όχι βαθμολογία της χώρας από μόνη της — διάβασέ τις λοιπόν σε σχέση μεταξύ τους. Δεν αθροίζουν ακριβώς σε 1: όλα κάτω από ένα τοις εκατό μένουν έξω, όπως και ό,τι βρίσκεται μετά την εικοστή πέμπτη χώρα.
Πόσο κοστίζει ένα ερώτημα χώρας προέλευσης;
Δύο credits ανά όνομα, γιατί είναι βαρύτερο ερώτημα από μια απλή αναγνώριση φύλου. Τα credits ξεκινούν από €0.35 ανά 1.000, αγοράζονται προκαταβολικά και δεν λήγουν.
Είναι το ίδιο με την παράμετρο country που στέλνω;
Όχι — είναι αντίθετες κατευθύνσεις. Το country, locale ή ip που στέλνεις περιγράφει πού βρίσκεται το πρόσωπο τώρα και αλλάζει ποιο φύλο επιστρέφει. Η χώρα προέλευσης που παίρνεις πίσω περιγράφει από πού προέρχεται το όνομα και δεν εξαρτάται από το πού ζει το πρόσωπο.
Μπορώ να περάσω μια ολόκληρη λίστα;
Ναι. Η παραλλαγή batch παίρνει έως 100 ονόματα ανά αίτημα, χωρίς όριο στον αριθμό των αιτημάτων, και το ίδιο endpoint απαντά εξίσου καλά σε ένα μόνο όνομα.
Είναι νόμιμο κατά το GDPR να συνάγεις προέλευση από ένα όνομα;
Εξαρτάται από το τι κάνεις με αυτό, και είναι δική σου απόφαση ως υπεύθυνος επεξεργασίας, όχι δική μας. Τα δεδομένα που δείχνουν εθνοτική προέλευση είναι ειδική κατηγορία κατά το άρθρο 9, οπότε η χρήση τους για αποφάσεις σχετικά με συγκεκριμένα πρόσωπα απαιτεί νομική βάση που μπορείς να αποδείξεις. Οι συγκεντρωτικές αναλύσεις και οι σωστές προσφωνήσεις είναι οι συνήθεις χρήσεις. Είμαστε γερμανική εταιρεία, όλοι οι διακομιστές βρίσκονται στη Γερμανία, και σύμβαση επεξεργασίας δεδομένων μπορείς να ζητήσεις από τον λογαριασμό σου.
ΔΟΚΙΜΑΣΕ ΤΟ ΣΕ ΟΝΟΜΑΤΑ ΠΟΥ ΗΔΗ ΞΕΡΕΙΣ
100 δωρεάν ερωτήματα τον μήνα, χωρίς κάρτα. Ξεκίνα με ονόματα των οποίων την προέλευση μπορείς να ελέγξεις μόνος σου — είναι ο γρηγορότερος τρόπος να δεις τι σου λέει η κατανομή.
Τεκμηρίωση API · Επεξεργάσου μια ολόκληρη λίστα · Κάνε μια ερώτηση
