DOKUMENTACE API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Získání země původu (v2)
PURPOSE: Zjistěte pravděpodobnou zemi původu a etnický původ na základě jmen.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <Váš autorizační token> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Křestní jméno pro vyhledávání

Parameter: full_name
  Type: string
  Required: OPTIONAL
  Description: Celé jméno pro vyhledávání. Může být zadáno místo pole first_name

Parameter: email
  Type: string
  Required: OPTIONAL
  Description: E-mailová adresa pro vyhledávání. Může být zadána místo pole first_name

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maximálně 50 znaků. Můžete nastavit toto ID na libovolnou alfanumerickou hodnotu, kterou chcete."}, { 

--- REQUEST EXAMPLES ---

Example 1: Dotaz podle křestního jména
Request Body (JSON):
{
    "first_name": "Johann"
}

Example 2: Vyhledávání podle celého jména
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 3: Vyhledávání podle e-mailové adresy
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: Odeslaná užitečná zátěž

Field: details.credits_used
  Type: int
  Description: Počet požadavků použitých pro toto vyhledávání

Field: details.samples
  Type: int
  Description: Počet záznamů nalezených v naší databázi, které odpovídají vašemu požadavku

Field: details.country
  Type: string
  Description: Země, kterou jsme našli

Field: details.first_name_sanitized
  Type: string
  Description: Jméno po použití našeho normalizátoru

Field: details.duration
  Type: string
  Description: Čas potřebný serveru ke zpracování požadavku

Field: result_found
  Type: bool
  Description: Pravda, pokud bylo možné vyhledat pohlaví pro dané jméno

Field: country_of_origin_map_url
  Type: string
  Description: URL adresa interaktivní mapy o tomto jménu

Field: first_name
  Type: string
  Description: Křestní jméno, které jsme použili pro genderizaci

Field: probability
  Type: float
  Description: Tato hodnota (mezi 0 a 1) určuje spolehlivost naší databáze. Hodnota 1 znamená, že výsledky vašeho požadavku na pohlaví jsou 100% přesné

Field: gender
  Type: string
  Description: Možné hodnoty: mužské, ženské, neznámé

Field: country_of_origin
  Type: object
  Description: Top 25 zemí původu. Podrobnosti naleznete v "Úplný seznam možných zemí" pro seznam podporovaných zemí. Každý záznam obsahuje pole country_name, country, probability, continental_region a statistical_region

Field: language_of_origin
  Type: string
  Description: Jazyk původu tohoto jména

Field: meaning
  Type: string
  Description: Stručný popis významu tohoto jména

Field: ethnicity
  Type: object
  Description: Pole etnické příslušnosti poskytuje podrobnosti o hlavní etnické skupině spojené s tímto jménem, a také o tom, jak je jméno rozloženo mezi různé etnické skupiny

Field: ethnicity.id
  Type: string
  Description: Pole ID obsahuje identifikátor určené hlavní etnické skupiny. Úplný seznam možných etnických skupin naleznete v "Kompletní seznam všech možných etnických skupin"

Field: ethnicity.name
  Type: string
  Description: Pole jméno obsahuje název určené hlavní etnické skupiny. Úplný seznam možných etnických skupin naleznete v "Complete List Of Possible Ethnic Groups"

Field: ethnicity.distribution
  Type: array
  Description: Pole Rozložení obsahuje informace o podílu jména v rámci různých etnických skupin. Každý prvek pole obsahuje pole id (řetězec), name (řetězec) a percentage (desetiné číslo). Úplný seznam možných hodnot naleznete v "Complete List Of Possible Ethnic Groups"

--- 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 <Váš autorizační token> link' \
  -d '{"first_name":"Johann"}'

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

=== END OF INSTRUCTIONS ===