Κατανόηση της απόκρισης JSON
Οι μεμονωμένες προβλέψεις του GenderAPI.io V2 επιστρέφουν ένα πεδίο data για το αποτέλεσμα και ένα πεδίο meta για τις πληροφορίες αιτήματος, πρόσβασης και χρέωσης. Διαβάστε τα data.gender και data.confidence μαζί με τα data.confidence_kind και data.source. Το παρακάτω παράδειγμα από το σύνολο δεδομένων είναι μια πραγματική απόκριση που λήφθηκε την 1η Οκτωβρίου 2026 με κλειδί API. Αντικαταστάθηκε μόνο το υπόλοιπο του λογαριασμού. Δεν αντιπροσωπεύει μετρημένη ακρίβεια του προϊόντος και ένα αίτημα σε πραγματικό χρόνο μπορεί να επιστρέψει διαφορετικό αποτέλεσμα. Τα αιτήματα με κλειδί API επιστρέφουν access.mode: api_key και null στα πεδία ορίου που ισχύουν μόνο για τη δοκιμαστική πρόσβαση, ενώ τα αιτήματα μέσω της δοκιμαστικής πρόσβασης IP επιστρέφουν ip_trial μαζί με το όριο της δοκιμαστικής πρόσβασης και τον χρόνο επαναφοράς.
{
"data": {
"input": {
"type": "name",
"value": "Γιώργος",
"country": "GR"
},
"name": "γιώργος",
"gender": "male",
"country": "GR",
"confidence": 0.9958419958419958,
"confidence_kind": "observed_frequency",
"sample_count": 481,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "γιώργος",
"method": "normalized",
"scope": "country",
"country": "GR"
}
},
"meta": {
"request_id": "6e0323de-a249-46fe-88fc-9d60bfd59bd3",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Πεδία απόκρισης πρόβλεψης
| Πεδίο | Τύπος | Μπορεί να είναι null | Παράδειγμα | Περιγραφή |
|---|---|---|---|---|
data.input | object | Όχι | {"type":"name","value":"Γιώργος","country":"GR"} | Τύπος εισόδου, τιμή και χώρα. Το forceToGenderize περιλαμβάνεται όταν είναι true. |
data.name | string | Ναι | "γιώργος" | Μικρό όνομα που αντιστοιχίστηκε ή εξήχθη. null όταν δεν είναι διαθέσιμο. |
data.gender | string | Ναι | "male" | male, female ή JSON null. Πρόκειται για πρόβλεψη, όχι για επαληθευμένη ταυτότητα ενός ατόμου. |
data.result_status | string | Όχι | "identified" | identified όταν επιστρέφεται φύλο, διαφορετικά unknown. |
data.reason | string | Ναι | null | null για τα αποτελέσματα identified. Λόγοι για unknown: not_found, no_name_candidate, ambiguous ή insufficient_evidence. |
data.confidence | number | Ναι | 0.95 | Τιμή από 0 έως 1 ή null. Όταν το gender είναι null, και ο βαθμός βεβαιότητας είναι null. |
data.confidence_kind | string | Ναι | "observed_frequency" | observed_frequency: το πλήθος της επικρατέστερης κατηγορίας στο σύνολο δεδομένων διαιρεμένο με το συνολικό πλήθος. model_reported: τιμή που αναφέρει το AI, όχι βαθμονομημένη πιθανότητα. null όταν δεν είναι διαθέσιμη. |
data.sample_count | integer | Ναι | 1200 | Μέγεθος δείγματος στο σύνολο δεδομένων ή null. Το AI δεν επινοεί πλήθος δειγμάτων. |
data.source | string | Όχι | "dataset" | dataset, ai ή none. |
data.country | string | Ναι | "GR" | Συσχέτιση χώρας από dataset ή ai_association ή null. Δεν καθορίζει εθνικότητα, τόπο κατοικίας ούτε εθνοτική καταγωγή. |
data.country_source | string | Ναι | "dataset" | Προέλευση της συσχέτισης χώρας: dataset, ai_association ή null. |
data.match | object | Όχι | {"name":"γιώργος","method":"normalized","scope":"country","country":"GR"} | Όνομα που αντιστοιχίστηκε στο σύνολο δεδομένων, μέθοδος (normalized, token, substring ή model_inference), εύρος country ή global και χώρα της αντιστοίχισης. Τα τεκμήρια που δεν είναι διαθέσιμα είναι null. |
Πεδία εισόδου που επιστρέφονται
| Πεδίο | Τύπος | Μπορεί να είναι null | Παράδειγμα | Περιγραφή |
|---|---|---|---|---|
data.input.type | string | Όχι | "name" | Κατηγορία εισόδου: name, email ή username. |
data.input.value | string | Όχι | "Γιώργος" | Η τιμή που στάλθηκε για πρόβλεψη. |
data.input.country | string | Ναι | "GR" | Το πλαίσιο χώρας που στάλθηκε. null αν παραλείφθηκε. |
data.input.forceToGenderize | boolean | Όχι | true | Υπάρχει μόνο όταν είναι ενεργή η λειτουργία ψευδωνύμων. Διαφορετικά παραλείπεται. |
Πεδία αντιστοίχισης στο σύνολο δεδομένων
| Πεδίο | Τύπος | Μπορεί να είναι null | Παράδειγμα | Περιγραφή |
|---|---|---|---|---|
data.match.name | string | Ναι | "γιώργος" | Ο υποψήφιος που επιλέχθηκε στο σύνολο δεδομένων. null αν δεν επιλέχθηκε γραμμή του συνόλου δεδομένων. |
data.match.method | string | Ναι | "normalized" | normalized, token, substring ή model_inference. null αν δεν είναι διαθέσιμο. |
data.match.scope | string | Ναι | "country" | country ή global για αναζητήσεις στο σύνολο δεδομένων. null για το AI ή όταν δεν υπάρχουν τεκμήρια. |
data.match.country | string | Ναι | "GR" | Χώρα της γραμμής του συνόλου δεδομένων που επιλέχθηκε. null για καθολικές γραμμές ή για το AI. |
Μεταδεδομένα πρόσβασης, χρέωσης και αιτήματος
| Πεδίο | Τύπος | Μπορεί να είναι null | Παράδειγμα | Περιγραφή |
|---|---|---|---|---|
meta.request_id | string | Όχι | "550e8400-e29b-41d4-a716-446655440000" | Μοναδικό αναγνωριστικό αυτής της απόπειρας HTTP. Αποστέλλεται και στο X-Request-ID. |
meta.duration_ms | integer | Όχι | 42 | Χρόνος επεξεργασίας του αιτήματος σε χιλιοστά του δευτερολέπτου. |
meta.access.mode | string | Όχι | "api_key" | api_key, ip_trial ή unauthenticated. Με λογαριασμό επί πληρωμή ελέγξτε ότι επιστρέφεται api_key. |
meta.access.reason | string | Ναι | null | Λόγος μετάβασης στη δοκιμαστική πρόσβαση IP: api_key_missing, api_key_invalid ή api_key_not_found. Διαφορετικά null. |
meta.usage.charged_credits | integer | Ναι | 1 | Καθαρές πιστώσεις που χρεώθηκαν. Μηδέν πριν από τη χρέωση ή μετά από πλήρη επιβεβαιωμένη επιστροφή πιστώσεων. null όταν η χρέωση δεν έχει επιβεβαιωθεί. |
meta.usage.remaining_credits | integer | Ναι | 99 | Υπόλοιπο κατά την ολοκλήρωση της λειτουργίας. Μπορεί να είναι αρνητικό. null αν δεν είναι διαθέσιμο ή αν η χρέωση δεν έχει επιβεβαιωθεί. |
meta.usage.billing_status | string | Όχι | "confirmed" | not_charged, confirmed ή unconfirmed. Ελέγξτε το πριν επαναλάβετε μια πρόβλεψη που απέτυχε. |
meta.usage.resets_at | string | Ναι | "2026-09-27T12:00:00.000Z" | Χρονική στιγμή επαναφοράς της δοκιμαστικής πρόσβασης IP σε UTC (ISO 8601). null για λογαριασμούς με κλειδί API ή όταν είναι άγνωστη. |
meta.usage.limit | integer | Ναι | 10 | Όριο πιστώσεων της δοκιμαστικής πρόσβασης IP. null για λογαριασμούς με κλειδί API. |
meta.usage.period_seconds | integer | Ναι | 86400 | Διάρκεια της περιόδου της δοκιμαστικής πρόσβασης IP σε δευτερόλεπτα. null για λογαριασμούς με κλειδί API. |
Ένα επιτυχές άγνωστο αποτέλεσμα
Το HTTP 200 σημαίνει ότι η λειτουργία ολοκληρώθηκε, όχι ότι επιστράφηκε οπωσδήποτε φύλο. Διατηρήστε την τιμή JSON null αντί να τη μετατρέψετε σε male, female, κενή συμβολοσειρά ή μηδενικό βαθμό βεβαιότητας. Ελέγξτε τα data.result_status και data.reason ξεχωριστά από τα σφάλματα HTTP.
Αυτό το πραγματικό παράδειγμα μόνο με το σύνολο δεδομένων, που λήφθηκε την 1η Οκτωβρίου 2026, επιστρέφει source: none και reason: not_found και κοστίζει και πάλι 1 πίστωση. Μια γραμμή του συνόλου δεδομένων με ισοπαλία μπορεί να επιστρέψει reason: ambiguous και να διατηρήσει το sample_count. Ένα άγνωστο αποτέλεσμα του AI χρησιμοποιεί source: ai και reason: insufficient_evidence.
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}Ερμηνεία του βαθμού βεβαιότητας και των τεκμηρίων αντιστοίχισης
Ένας βαθμός βεβαιότητας 0.9 εκφράζεται σε κλίμακα από 0 έως 1. Για το observed_frequency σημαίνει το επικρατέστερο πλήθος διαιρεμένο με το σύνολο της επιλεγμένης γραμμής του συνόλου δεδομένων. Δεν είναι ακρίβεια του προϊόντος μετρημένη από άκρο σε άκρο. Μια τιμή model_reported παρέχεται από το AI και δεν είναι βαθμονομημένη με βάση τις συχνότητες του συνόλου δεδομένων.
Ορίστε τα όρια της εφαρμογής σας με βάση τα δικά σας δεδομένα αξιολόγησης και το confidence_kind. Μην κατατάσσετε απευθείας στην ίδια κλίμακα τις τιμές του συνόλου δεδομένων και του AI, σαν να μετρούσαν το ίδιο πράγμα. Για το AI, τα match.name, match.scope και match.country είναι null επειδή δεν επιλέχθηκε γραμμή του συνόλου δεδομένων. Το match.method είναι model_inference.
Στα πλήρη ονόματα, ένα αποτέλεσμα του συνόλου δεδομένων μπορεί να προέρχεται από ένα μέρος του ονόματος και όχι από ολόκληρη τη συμβολοσειρά. Το data.input διατηρεί την τιμή που στάλθηκε, το data.name περιγράφει το όνομα που επιστράφηκε και το data.match τον υποψήφιο και το εύρος της αναζήτησης.
Αποφασίστε τι πρέπει να κάνει η εφαρμογή σας
Χειριστείτε πρώτα τα σφάλματα του αιτήματος και των μεμονωμένων στοιχείων και έπειτα ελέγξτε το result_status. Σε μια μεμονωμένη πρόβλεψη διαβάστε το data. Σε μια παρτίδα εφαρμόστε την ίδια απόφαση στο data κάθε επιτυχούς στοιχείου. Διατηρήστε τα άγνωστα αποτελέσματα στην εφαρμογή σας αντί να επιβάλλετε την ετικέτα male ή female.
| Αποτέλεσμα | Τι σημαίνει | Προτεινόμενος χειρισμός |
|---|---|---|
| identified, gender: male ή female | Η πρόβλεψη επέστρεψε φύλο, με βάση το σύνολο δεδομένων ή το AI. | Εφαρμόστε έναν κανόνα που αξιολογήθηκε για το συγκεκριμένο confidence_kind. Διατηρήστε το source και τα τεκμήρια της αντιστοίχισης. |
| unknown, reason: not_found | Καμία αποθηκευμένη εγγραφή του συνόλου δεδομένων δεν αντιστοιχεί στους υποψηφίους που ερμηνεύτηκαν. | Αφήστε το gender ως null. Ένα σκόπιμο νέο αίτημα με άλλες επιλογές AI είναι νέα χρεώσιμη λειτουργία. |
| unknown, reason: no_name_candidate | Η ερμηνεία για το σύνολο δεδομένων δεν έδωσε αξιοποιήσιμο υποψήφιο ονόματος. | Διατηρήστε το null. Ελέγξτε τον τύπο εισόδου και την τιμή πριν επιλέξετε πρόσθετη πρόβλεψη. |
| unknown, reason: ambiguous | Η επιλεγμένη γραμμή του συνόλου δεδομένων έχει τον ίδιο αριθμό ανδρικών και γυναικείων εμφανίσεων. Το sample_count μπορεί ωστόσο να υπάρχει. | Μην αποφασίζετε εσείς ποιο φύλο ισχύει και μη μετατρέπετε τον βαθμό βεβαιότητας null σε μηδέν. |
| unknown, reason: insufficient_evidence | Το AI ολοκλήρωσε το αίτημα χωρίς επαρκή τεκμήρια για να επιστρέψει φύλο. | Χειριστείτε το ως ολοκληρωμένο άγνωστο αποτέλεσμα, όχι ως σφάλμα παρόχου ούτε ως υποψήφιο για αυτόματες νέες προσπάθειες. |
| Problem Details ή error ενός στοιχείου | Η εκτέλεση απέτυχε, για παράδειγμα λόγω ai_upstream_error ή prediction_timeout. | Αποθηκεύστε τον κωδικό σφάλματος και το αναγνωριστικό του αιτήματος, ελέγξτε τη χρέωση και ακολουθήστε τις οδηγίες για νέες προσπάθειες. |
Επιλογή ορίων με βάση τη δική σας αξιολόγηση
Δεν υπάρχει καθολικό όριο βαθμού βεβαιότητας που να κάνει μια πρόβλεψη σωστή. Αξιολογήστε το observed_frequency και το model_reported χωριστά, με αντιπροσωπευτικά παραδείγματα από τη δική σας περίπτωση χρήσης, με ετικέτες που έχουν οριστεί ανεξάρτητα. Μια συχνότητα στο σύνολο δεδομένων και μια τιμή που αναφέρει το AI είναι διαφορετικά σήματα, ακόμη κι όταν και τα δύο έχουν τιμή 0.9. Μετρήστε πόσο συχνά ο κανόνας σας δίνει απάντηση και πόσο συχνά αυτές οι απαντήσεις είναι σωστές. Σε όλες τις άλλες περιπτώσεις διατηρήστε ένα άγνωστο αποτέλεσμα ή προβλέψτε χειροκίνητο έλεγχο.
Αν, για παράδειγμα, το result_status είναι identified αλλά το confidence_kind είναι model_reported, εφαρμόστε τον κανόνα που αξιολογήσατε για το AI, όχι το όριο του συνόλου δεδομένων. Αν χρησιμοποιήθηκε το forceToGenderize, το name: null μαζί με φύλο διαφορετικό από null είναι έγκυρο: ένα ψευδώνυμο μπορεί να ερμηνευτεί χωρίς να εξαχθεί πραγματικό μικρό όνομα. Ελέγξτε τα gender και result_status, όχι μόνο το name, για να κρίνετε αν η πρόβλεψη έδωσε απάντηση. Το αποτέλεσμα παραμένει εκτίμηση, όχι επιβεβαίωση της ταυτότητας ενός ατόμου.