DOKUMENTACE API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Dotaz podle křestního jména (v2)
PURPOSE: Určení pohlaví z křestních jmen s volitelnou lokalizací země pro zvýšenou přesnost.

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

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

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Jméno k vyhledání

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 kód země link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Jazyk prohlížeče

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Platná IPv4 nebo IPv6 adresa

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 pouze podle křestního jména
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Dotaz podle křestního jména a kódu země
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Dotaz podle křestního jména a lokalizace prohlížeče
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Dotaz podle křestního jména a použití IP adresy pro lokalizaci
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Vyhledávání více jmen v jednom požadavku
Request Body (JSON):
[
    {
        "first_name": "Sandra",
        "country": "US"
    },
    {
        "first_name": "Jason",
        "country": "US"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "first_name": "Sandra"
    },
    "details": {
        "credits_used": 1,
        "samples": 464,
        "country": null,
        "first_name_sanitized": "sandra",
        "duration": "436ms"
    },
    "result_found": true,
    "first_name": "Sandra",
    "probability": 0.85,
    "gender": "female"
}

--- 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: 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 gender jsou 100% přesné.

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

--- 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/gender' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Váš autorizační token> link' \
  -d '{"first_name":"Sandra"}'

--- CREDIT USAGE ---
Required Requests: 1

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Vyhledávání podle celého jména (v2)
PURPOSE: Automaticky rozdělte celá jména a určete pohlaví v jednom efektivním volání API.

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

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

--- REQUEST PARAMETERS ---

Parameter: full_name
  Type: string
  Required: REQUIRED
  Description: Jméno k vyhledání

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 kód země link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Jazyk prohlížeče

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Platná IPv4 nebo IPv6 adresa

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: Vyhledávání pouze podle celého jména
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 2: Vyhledávání podle celého jména a kódu země
Request Body (JSON):
{
    "full_name": "Theresa Miller",
    "country": "US"
}

Example 3: Vyhledávání podle celého jména a jazykového nastavení prohlížeče
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Vyhledávání podle celého jména a použití IP adresy pro lokalizaci
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Vyhledávání více jmen v jednom požadavku
Request Body (JSON):
[
    {
        "full_name": "Theresa Miller"
    },
    {
        "full_name": "Thomas Johnson",
        "country": "US"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "full_name": "Theresa Miller"
    },
    "details": {
    "credits_used": 1,
        "duration": "33ms",
        "samples": 8961,
        "country": null,
        "first_name_sanitized": "theresa"
    },
    "result_found": true,
    "last_name": "Miller",
    "first_name": "Theresa",
    "probability": 0.98,
    "gender": "female"
}

--- 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.full_name_sanitized
  Type: int
  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: full_name
  Type: string
  Description: Celé 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 gender jsou 100% přesné.

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

--- 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/gender' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Váš autorizační token> link' \
  -d '{"full_name":"Theresa Miller"}'

--- CREDIT USAGE ---
Required Requests: 1

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Vyhledávání podle e-mailové adresy (v2)
PURPOSE: Extrakce jmen z e-mailových adres a určení pohlaví pomocí pokročilých parserovacích algoritmů.

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

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

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: E-mailová adresa pro vyhledávání

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: ISO 3166 ALPHA-2 kód země link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Jazyk prohlížeče

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Platná IPv4 nebo IPv6 adresa

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: Vyhledávání pouze podle e-mailové adresy
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: Vyhledávání podle e-mailové adresy a kódu země
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: Vyhledávání podle e-mailové adresy a nastavení jazyka prohlížeče
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: Vyhledávání podle e-mailové adresy a použití IP adresy pro lokalizaci
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: Vyhledávání více jmen v jednom požadavku
Request Body (JSON):
[
    {
        "email": "thomas.clarks@hotmail.com",
        "country": "US"
    },
    {
        "email": "theresa.miller14@gmail.com"
    }
]

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "input": {
        "email": "theresa.miller14@gmail.com"
    },
    "details": {
        "credits_used": 1,
        "duration": "12ms",
        "samples": 8961,
        "country": null,
        "first_name_sanitized": "theresa"
    },
    "result_found": true,
    "last_name": "Miller",
    "first_name": "Theresa",
    "probability": 0.98,
    "gender": "female"
}

--- 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.email_sanitized
  Type: int
  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: email
  Type: string
  Description: E-mailová adresa, kterou jsme použili pro určení pohlaví

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 gender jsou 100% přesné.

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

--- 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/gender' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Váš autorizační token> link' \
  -d '{"email":"theresa.miller14@gmail.com"}'

--- CREDIT USAGE ---
Required Requests: 1

=== END OF INSTRUCTIONS ===

=== 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 ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Získat statistiky (v2)
PURPOSE: Získejte podrobné statistiky využití a zbývající kredity pro váš účet.

--- API DETAILS ---
Method: GET
URL: https://gender-api.com/v2/statistic

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

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "is_limit_reached": false,
    "remaining_credits": 24999,
    "details": {
        "credits_used": 0,
        "duration": "83ms"
    },
    "usage_last_month": {
        "date": "2018-03",
        "credits_used": 25
    }
}

--- RESPONSE FIELDS ---

Field: is_limit_reached
  Type: bool
  Description: Vrací hodnotu true, pokud nezbývají žádné další požadavky

Field: remaining_credits
  Type: int
  Description: Počet zbývajících požadavků

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

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

Field: usage_last_month.date
  Type: string
  Description: Datum minulého měsíce

Field: usage_last_month.credits_used
  Type: int
  Description: Požadavky, které jste použili v posledním měsíci

--- 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 GET \
  'https://gender-api.com/v2/statistic' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Váš autorizační token> link' \

=== END OF INSTRUCTIONS ===