API-DOKUMENTATION

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Herkunftsland abfragen (v2)
PURPOSE: Entdecke das wahrscheinlichste Herkunftsland und den ethnischen Hintergrund basierend auf Namen.

--- API DETAILS ---
Method: POST
URL: https://gender-api.com/v2/country-of-origin

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <dein Autorisierungs-Token> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Vorname, der abgefragt werden soll

Parameter: full_name
  Type: string
  Required: OPTIONAL
  Description: Abzufragender vollständiger Name. Kann alternativ zum Feld first_name gesendet werden

Parameter: email
  Type: string
  Required: OPTIONAL
  Description: Abzufragende E-Mail-Adresse. Kann alternativ zum Feld first_name gesendet werden

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Max. 50 Zeichen. Du kannst diesem Feld einen beliebigen alphanumerischen Wert mitgeben. Als ID kann zum Beispiel die interne ID des Datensatzes aus deiner Datenbank gesetzt werden. In einer asynchronen Umgebung lässt sich unsere Antwort dadurch leichter der passenden Anfrage zuordnen

--- REQUEST EXAMPLES ---

Example 1: Abfrage anhand eines Vornamens
Request Body (JSON):
{
    "first_name": "Johann"
}

Example 2: Abfrage anhand eines vollständigen Namens
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 3: Abfrage anhand einer E-Mail-Adresse
Request Body (JSON):
{
    "full_name": "sophia5342@gmail.com"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "first_name": "Johann",
        "id": 12
    },
    "details": {
        "credits_used": 2,
        "duration": "414ms",
        "samples": 890,
        "country": null,
        "first_name_sanitized": "johann"
    },
    "result_found": true,
    "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"
        }
    ],
    "first_name": "Johann",
    "probability": 0.9,
    "gender": "male",
    "language_of_origin": "Germanic",
    "meaning": "Johann is the German variation of the name John, which means 'God is gracious'. It was frequently used in the Middle Ages across Europe, particularly as a name for religious figures.",
    "ethnicity": {
        "id": "GERMANIC",
        "name": "Germanic (German, Austrian, Swiss)",
        "distribution": [
            {
                "id": "GERMANIC",
                "name": "Germanic (German, Austrian, Swiss)",
                "percentage": 90
            },
            {
                "id": "DUTCH",
                "name": "Dutch",
                "percentage": 5
            },
            {
                "id": "FRENCH",
                "name": "French",
                "percentage": 5
            }
        ]
    }
 }

--- RESPONSE FIELDS ---

Field: input
  Type: object
  Description: Die übergebenen Daten

Field: details.credits_used
  Type: int
  Description: Die Anzahl der Anfragen, die für diese Abfrage nötig waren

Field: details.samples
  Type: int
  Description: Anzahl der Einträge, die zu deiner Anfrage in unserer Datenbank gefunden wurden

Field: details.country
  Type: string
  Description: Das gefundene Land

Field: details.first_name_sanitized
  Type: string
  Description: Der Name, nachdem wir ihn normalisiert haben

Field: details.duration
  Type: string
  Description: Zeit, die der Server für die Verarbeitung der Anfrage gebraucht hat

Field: result_found
  Type: bool
  Description: True, wenn wir ein Geschlecht zum angegebenen Namen bestimmen konnten

Field: country_of_origin_map_url
  Type: string
  Description: URL zu einer interaktiven Karte zu diesem Namen

Field: first_name
  Type: string
  Description: Der gefundene Vorname, den wir zur Bestimmung des Geschlechts genutzt haben

Field: probability
  Type: float
  Description: Dieser Wert (zwischen 0 und 1) bestimmt, wie sicher wir uns sind, das richtige Geschlecht gefunden zu haben. Ein Wert von 1 sagt aus, dass wir uns zu 100 % sicher sind

Field: gender
  Type: string
  Description: Mögliche Werte: male, female, unknown

Field: country_of_origin
  Type: object
  Description: Top 25 der Herkunftsländer. Eine Liste der unterstützten Länder findest du unter „Vollständige Liste der möglichen Länder“. Jeder Eintrag enthält die Felder country_name, country, probability, continental_region und statistical_region

Field: language_of_origin
  Type: string
  Description: Die Ursprungssprache dieses Namens

Field: meaning
  Type: string
  Description: Eine kurze Beschreibung der Bedeutung dieses Namens

Field: ethnicity
  Type: object
  Description: Das Feld ethnicity liefert Informationen über die primäre ethnische Gruppe, die mit dem Namen verbunden ist, sowie über die Verteilung des Namens auf verschiedene ethnische Gruppen

Field: ethnicity.id
  Type: string
  Description: Das Feld id enthält eine Kennung für die bestimmte ethnische Hauptgruppe. Eine vollständige Liste der möglichen ethnischen Gruppen findest du unter „Vollständige Liste der möglichen ethnischen Gruppen“

Field: ethnicity.name
  Type: string
  Description: Das Feld name enthält den Namen der bestimmten ethnischen Hauptgruppe. Eine vollständige Liste der möglichen ethnischen Gruppen findest du unter „Vollständige Liste der möglichen ethnischen Gruppen“

Field: ethnicity.distribution
  Type: array
  Description: Das Feld distribution enthält Informationen über den Anteil des Namens innerhalb verschiedener ethnischer Gruppen. Jeder Eintrag im Array enthält die Felder id (string), name (string) und percentage (float). Eine vollständige Liste der möglichen Werte findest du unter „Vollständige Liste der möglichen ethnischen Gruppen“

--- IMPLEMENTATION NOTES ---

1. Make sure to replace placeholder values:
   - Replace '' with your actual API key
   - Replace domain placeholders with the actual API domain

2. Handle errors appropriately:
   - Check HTTP status codes
   - Parse error responses
   - Implement retry logic for transient failures

3. Best Practices:
   - Store API keys securely (use environment variables)
   - Implement rate limiting on your side
   - Cache responses when appropriate
   - Use HTTPS for all requests
   - Set appropriate timeout values

4. RECOMMENDED: Implement the Statistics Endpoint
   - The statistics endpoint allows users to monitor their credit usage
   - Users can see how many credits they have used and how many are left
   - This helps prevent unexpected service interruptions
   - API v1: GET /get-stats?key=YOUR_API_KEY
   - API v2: GET /v2/statistic (with Authorization Bearer token)
   - Display remaining credits in your application's UI
   - Consider adding alerts when credits are running low

--- IMPLEMENTATION TEMPLATE ---

// Example implementation in cURL:
curl -X POST \
  'https://gender-api.com/v2/country-of-origin' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <dein Autorisierungs-Token> link' \
  -d '{"first_name":"Johann"}'

--- CREDIT USAGE ---
Required Requests: 2

=== END OF INSTRUCTIONS ===