Addan uyruk: bir ad neyi söyleyebilir, neyi söyleyemez
Tek bir API çağrısı, bir adı veya soyadı, geldiği ülkelerin sıralı bir listesine dönüştürür; her birinde bir olasılıkla. Ad hakkındaki bir soruya yanıt verir — bu, kişinin nerede yaşadığından farklı bir soru, kim olduğundan ise bambaşka bir soru.
Kısa yanıt
- En fazla 25 ülkeden oluşan sıralı bir liste alırsın; her biri bir olasılık, bir ISO kodu, bir ülke adı ve ülke için kayıtlıysa kıtasal ve istatistiksel bölgesiyle.
- Aynı yanıt cinsiyeti, köken dilini, adın anlamını ve etnik gruplara dağılımını da içerir; 192 ülkeyi kapsayan bir veritabanından.
- Ad başına 2 credits tutar — düz bir cinsiyet sorgusunun iki katı, çünkü daha ağır bir sorgu. Credits önceden satın alınır ve süresi dolmaz.
- Bu, ad hakkında bir istatistik, kişi hakkında bir iddia değil. Hitap, toplu analiz ve veri kalitesi için kullan — tek bir insan hakkında bir şeye karar vermek için değil.
Sayı nereden geliyor?
Burada tahmin yürüten bir model yok ve hiçbir şey üretilmiyor. Olasılık, gerçekten elimizde olan kayıtlar üzerinde aritmetiktir — bu yüzden aynı ad bugün, gelecek ay ve gelecek yıl aynı listeyi döndürür.
İki sinyal girer. Birincisi, o ada ait kayıtların ülkelere nasıl dağıldığı — çoğunlukla Polonya'dan elimizde olan bir ad Lehçeye yatkındır. İkincisi, bu nüfusların her birinin ne kadar büyük olduğu; bu da iyi örneklenmiş bir ada sahip küçük bir ülkenin salt hacimle büyük bir ülkeyi geçmesini engeller. İkisi ülke başına ortalanır, yüzde birin altındaki her şey düşer, kalan sıralanır.
Bir dağılım olduğu için, iki ülkede yaygın olan bir ad kazanan seçmek yerine iki ülkeyle yanıt verir. İşe yarayan tam da bu: listenin biçimi, ilk kayda ne kadar güvenebileceğini söyler.
Ne döner
Bir POST, bir ad, bir yanıt. Aşağıdaki liste kısaltılmış; gerçek olan en olası 25 ülkeye kadar gider.
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" }
}Yanıtı denetlenebilir kılan iki alana dikkat et: samples yanıtın kaç kayda dayandığını söyler, credits_used iki credits'i doğrular. Az örneğe dayanan bir yanıt senden saklanmaz.
- continental_region ve statistical_region ile listeyi kendi eşlemeni tutmadan bölgeye toplayabilirsin.
- Yanıt ayrıca o adın etkileşimli bir haritasına bağlantı içerir — bir sonucu gözle kontrol etmenin en hızlı yolu.
- Her alan v2 referansında belgelenmiştir.
Köken, ikamet değildir
Bu en sık yapılan yanlış okuma ve iki yöne de işler. İki farklı alan, iki farklı anlam, zıt yönler.
| Soru | Gönderdiğin ülke | Geri aldığın ülke |
|---|---|---|
| Alan | country, locale, ip |
country_of_origin |
| Anlamı | Kişinin şu anda nerede olduğu | Adın nereden geldiği |
| Cinsiyet yanıtını değiştirir | Evet — Andrea İtalya'da erkek, Almanya'da kadındır | Hayır — bu bir çıktı, girdi değil |
| Genellikle bunu zaten biliyorsun | Evet — teslimat adresinden, alan adından veya IP'den | Hayır — satın aldığın şey tam olarak bu |
| Credits | Ücretsiz — bir parametre, sorgu değil | Ad başına 2 |
Bunun ne olmadığı
Bir ad, bir ad hakkında kanıttır. Onu bir kişi hakkında kanıt saymak, bu tür verinin yanlış gittiği yerdir; bu yüzden üzerine bir şey inşa etmeden önce sınırlar hakkında açık konuşmaya değer.
Nguyen adlı biri Melbourne'de doğmuş olabilir, Smith adlı biri ise İngilizce konuşulan bir ülkeye hiç ayak basmamış olabilir. Endpoint “bu ad nereden geliyor” sorusuna yanıt verir ve yanıt verdiği tek soru budur.
- Bu bir uyruk, bir vatandaşlık ya da bir doğum yeri değildir — ve üçünden hiçbirinin kanıtı da değildir.
- Bu, kişinin etnik kökeni değildir. Etnik dağılım adın gruplara nasıl yayıldığını anlatır: adın bir özelliği.
- Tek bir kişi hakkında hiçbir şeye karar vermemeli — ne bir fiyata, ne bir başvuruya, ne bir risk puanına. Etnik kökene işaret eden veriler GDPR'ın 9. maddesi uyarınca özel bir kategoridir ve bu karar veri sorumlusu olarak sana aittir, bize değil.
- Bu bir tahmin değildir. Elimizde çok az olan yerde result_found false olur ve örnek sayısı bunu söyler — alanı doldurmak için makul bir ülke uydurulmaz.
Bizim tarafta: Alman bir şirketiz, tüm sunucular Almanya'da, veriler AB içinde işlenir ve veri işleme sözleşmesini hesabından talep edebilirsin. Tam tablo gizlilik özetinde.
Gerçekte ne için kullanılıyor
- Hitabı doğru yapmak. Bir adın Almanca değil İtalyanca olduğunu bilmek, “Andrea”yı yanlış selamlamadan doğrusuna çeviren şeydir — ve aynı yanıttaki cinsiyet sorgusu bunu uygulayan kısımdır.
- Toplu düzeyde pazar ve kitle analizi. Bir kampanyanın hangi dile çevrileceği, bir posta listesinin gerçekte hangi bölgelere ulaştığı, bir müşteri tabanının nerede büyüdüğü.
- Veri kalitesi. Köken dağılımının aniden biçim değiştirdiği bir liste genellikle bir içe aktarmanın yanlış gittiği anlamına gelir, kitlenin taşındığı anlamına değil.
- Araştırma ve demografi; burada bütün bir kohort üzerinde ad düzeyindeki dağılım analiz birimidir ve tek tek kişiler hakkında sonuç çıkarılmaz.
- Harf çevirisi ve eşleştirme; bir adın olası kökenini bilmek makul yazımlarını daraltır.
Bir liste üzerinde çalıştırmak
Toplu biçim istek başına 100 ada kadar alır, istek sayısında üst sınır yoktur. Payload düz bir JSON dizisidir.
POST https://gender-api.com/v2/country-of-origin
[
{ "first_name": "Johann" },
{ "full_name": "Andrea Rossi" }
]- Ad yerine tam bir isim ya da bir e-posta adresi de çalışır — önce ad çıkarılır, sonra köken çözülür.
- PHP, Python, Node, Java, Go, Ruby, Rust, Perl ve .NET için resmi istemciler.
- Bir entegrasyon değil de tek seferlik bir liste için toplu cinsiyet sorgusuna bak — aynı credits, kod yok.
- Her alan, her hata ve bir OpenAPI açıklaması: v2 referansı.
Sık sorulan sorular
Bir kişinin uyruğunu adından anlayabilir misin?
Hayır, ve dürüst hiçbir servis bunu yapamaz. Aldığın şey, adın nerede ve ne kadar güçlü göründüğü, ülkeye göre sıralanmış — ad hakkında bir istatistik, onu taşıyan kişi hakkında bir olgu değil. Pek çok insan, kökeni doğduğu yerle hiç ilgisi olmayan bir ad taşır.
Endpoint ne döndürür?
En fazla 25 ülkeden oluşan sıralı bir liste; her biri bir olasılık, bir ISO ülke kodu, bir ülke adı ve — ülke için kayıtlıysa — kıtasal ve istatistiksel bölgesiyle. Aynı yanıt cinsiyeti, köken dilini, adın anlamını ve etnik gruplara dağılımını da içerir.
Olasılık nasıl hesaplanıyor?
İki sinyalden: o ad için elimizdeki kayıtların hangi ülkeden ne kadarının geldiği ve bu nüfusların her birinin ne kadar büyük olduğu. İkisi ülke başına ortalanır, yüzde bir ve altındaki ülkeler düşer, kalanı sıralanır. Her değer, o ülkenin tek başına puanı değil, bütünün içindeki payıdır — dolayısıyla onları birbirine göre oku. Tam olarak 1'e tamamlanmazlar: yüzde birin altındaki her şey dışarıda kalır, yirmi beşinci ülkeden sonrası da.
Köken ülke sorgusu ne kadar tutar?
Ad başına iki credits, çünkü düz bir cinsiyet sorgusundan daha ağır bir sorgu. Credits 1.000 başına €0.35'den başlar, önceden satın alınır ve süresi dolmaz.
Bu, gönderdiğim country parametresiyle aynı şey mi?
Hayır — bunlar ters yönler. Gönderdiğin country, locale veya ip kişinin şu anda nerede olduğunu anlatır ve hangi cinsiyetin döneceğini değiştirir. Geri aldığın köken ülke ise adın nereden geldiğini anlatır ve kişinin nerede yaşadığına bağlı değildir.
Bütün bir listeyi geçirebilir miyim?
Evet. Toplu varyant istek başına 100 ada kadar alır, istek sayısında üst sınır yoktur, ve aynı endpoint tek bir ada da aynı şekilde yanıt verir.
GDPR kapsamında bir addan köken çıkarmak hukuka uygun mu?
Bu, onunla ne yaptığına bağlı ve veri sorumlusu olarak senin kararın, bizim değil. Etnik kökene işaret eden veriler 9. madde uyarınca özel bir kategoridir, dolayısıyla bunları belirli kişiler hakkında karar vermek için kullanmak, gösterebileceğin bir hukuki dayanak gerektirir. Toplu analizler ve doğru hitap alışılmış kullanımlardır. Alman bir şirketiz, tüm sunucular Almanya'da ve veri işleme sözleşmesini hesabından talep edebilirsin.
ZATEN BİLDİĞİN ADLARLA DENE
Ayda 100 ücretsiz sorgu, kredi kartı yok. Kökenini kendin doğrulayabileceğin adlarla başla — dağılımın sana ne anlattığını görmenin en hızlı yolu bu.
