DOKUMENTACJA API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Sign Up (v2)
PURPOSE: Create a free account and receive a login password and an API token. No authentication required.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: The email address to register. No first or last name is required.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Must be true. The user must consent to the Terms and Conditions and Privacy Policy.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Subscribe to the newsletter. Defaults to false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Account language. One of en, de, es. Defaults to en.

--- REQUEST EXAMPLES ---

Example 1: Sign up with an email address
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Sign up and subscribe to the newsletter
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true,
    "newsletter": true,
    "locale": "en"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "email": "user@example.com",
    "password": "",
    "api_token": "",
    "free_requests_per_month": 100,
    "status": "awaiting_activation",
    "message": "Account created. Ask the user to click the activation link sent to their email address. The API token below activates automatically once the email is confirmed and can then be used as a Bearer token against the API.",
    "docs_url": "https://gender-api.com/skill.md"
}

--- RESPONSE FIELDS ---

Field: email
  Type: string
  Description: The registered email address.

Field: password
  Type: string
  Description: A random login password for the web dashboard. Returned only once; store it securely. The user can reset it later via the forgot-password flow.

Field: api_token
  Type: string
  Description: The API bearer token. Use it as "Authorization: Bearer " for /v2/... requests. It starts working once the user confirms their email.

Field: free_requests_per_month
  Type: int
  Description: The number of free requests granted per month.

Field: status
  Type: string
  Description: The account status. "awaiting_activation" until the email address is confirmed.

Field: message
  Type: string
  Description: Human-readable guidance on the next step (confirming the email address).

Field: docs_url
  Type: string
  Description: Link to the prompt-ready AI implementation instructions (skill.md).

--- 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/sign-up' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","accept_terms":true}'

--- CREDIT USAGE ---
Required Requests: 0

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Zapytanie po imieniu (v2)
PURPOSE: Określ płeć na podstawie imion z opcjonalną lokalizacją kraju dla jeszcze większej dokładności.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <twój token autoryzacyjny> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Imię do zapytania

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: Kod kraju ISO 3166 ALPHA-2 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Lokalizacja przeglądarki

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Poprawny adres IPv4 lub IPv6

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksymalnie 50 znaków. Id może być ustawione na dowolną alfanumeryczną wartość.
            Na przykład możesz ustawić id na swoje wewnętrzne id zbioru danych w bazie danych. W asynchronicznym 
            środowisku może to pomóc w lepszym połączeniu odpowiedzi z poprzednim żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie tylko poprzez imię
Request Body (JSON):
{
    "first_name": "Sandra"
}

Example 2: Zapytanie po imieniu i kodzie kraju
Request Body (JSON):
{
    "first_name": "Sandra",
    "country": "US"
}

Example 3: Zapytanie po imieniu i ustawieniach przeglądarki
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Zapytanie po imieniu i lokalizacji na podstawie adresu IP
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Zapytaj o wiele nazw w jednym żądaniu
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: Wysłany payload

Field: details.credits_used
  Type: int
  Description: Ilość użytych zapytań dla tej zapytania

Field: details.samples
  Type: int
  Description: Liczba rekordów znalezionych w naszej bazie danych, które pasują do twojego zapytania

Field: details.country
  Type: string
  Description: Znalezione przez nas kraj

Field: details.first_name_sanitized
  Type: string
  Description: Imię po zastosowaniu normalizacji

Field: details.duration
  Type: string
  Description: Czas potrzebny serwerowi na przetworzenie zapytania

Field: result_found
  Type: bool
  Description: Prawda jeżeli byliśmy w stanie uzyskać informacje o płci na podstawie podanego imienia

Field: first_name
  Type: string
  Description: Imię, które było użyte do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (między 0 a 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik twojego zapytania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: mężczyzna, kobieta, nieznana

--- 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 <twój token autoryzacyjny> link' \
  -d '{"first_name":"Sandra"}'

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

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Zapytanie po pełnym imieniu (v2)
PURPOSE: Automatycznie rozdzielaj pełne imiona i nazwiska oraz określaj płeć w jednym wydajnym wywołaniu API.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <twój token autoryzacyjny> 
link

--- REQUEST PARAMETERS ---

Parameter: full_name
  Type: string
  Required: REQUIRED
  Description: Imię do zapytania

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: Kod kraju ISO 3166 ALPHA-2 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Lokalizacja przeglądarki

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Poprawny adres IPv4 lub IPv6

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksymalnie 50 znaków. Id może być ustawione na dowolną alfanumeryczną wartość.
            Na przykład możesz ustawić id na swoje wewnętrzne id zbioru danych w bazie danych. W asynchronicznym 
            środowisku może to pomóc w lepszym połączeniu odpowiedzi z poprzednim żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie tylko po pełnej nazwie
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 2: Zapytanie po pełnej nazwie i kodzie kraju
Request Body (JSON):
{
    "full_name": "Theresa Miller",
    "country": "US"
}

Example 3: Zapytanie po pełnej nazwie i języku przeglądarki
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Zapytaj o pełne imię i nazwisko oraz użyj adresu IP do lokalizacji
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Zapytaj o wiele nazw w jednym żądaniu
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: Wysłany payload

Field: details.credits_used
  Type: int
  Description: Ilość użytych zapytań dla tej zapytania

Field: details.samples
  Type: int
  Description: Liczba rekordów znalezionych w naszej bazie danych, które pasują do twojego zapytania

Field: details.country
  Type: string
  Description: Znalezione przez nas kraj

Field: details.full_name_sanitized
  Type: int
  Description: Imię po zastosowaniu normalizacji

Field: details.duration
  Type: string
  Description: Czas potrzebny serwerowi na przetworzenie zapytania

Field: result_found
  Type: bool
  Description: Prawda jeżeli byliśmy w stanie uzyskać informacje o płci na podstawie podanego imienia

Field: full_name
  Type: string
  Description: Pełne imię, które użyliśmy do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (między 0 a 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik twojego zapytania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: mężczyzna, kobieta, nieznana

--- 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 <twój token autoryzacyjny> link' \
  -d '{"full_name":"Theresa Miller"}'

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

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Zapytanie po adresie e‑mail (v2)
PURPOSE: Wyodrębnij imiona z adresów e‑mail i określ płeć dzięki zaawansowanym algorytmom parsującym.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <twój token autoryzacyjny> 
link

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: Adres e-mail do zapytania

Parameter: country
  Type: string
  Required: OPTIONAL
  Description: Kod kraju ISO 3166 ALPHA-2 link

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Lokalizacja przeglądarki

Parameter: ip
  Type: string
  Required: OPTIONAL
  Description: Poprawny adres IPv4 lub IPv6

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksymalnie 50 znaków. Id może być ustawione na dowolną alfanumeryczną wartość.
            Na przykład możesz ustawić id na swoje wewnętrzne id zbioru danych w bazie danych. W asynchronicznym 
            środowisku może to pomóc w lepszym połączeniu odpowiedzi z poprzednim żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytaj tylko według adresu e-mail
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: Zapytaj według adresu e-mail i kodu kraju
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: Zapytaj według adresu e-mail i ustawień regionalnych przeglądarki
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: Zapytaj według adresu e-mail i użyj adresu IP do określenia lokalizacji
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: Zapytaj o wiele nazw w jednym żądaniu
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: Wysłany payload

Field: details.credits_used
  Type: int
  Description: Ilość użytych zapytań dla tej zapytania

Field: details.samples
  Type: int
  Description: Liczba rekordów znalezionych w naszej bazie danych, które pasują do twojego zapytania

Field: details.country
  Type: string
  Description: Znalezione przez nas kraj

Field: details.email_sanitized
  Type: int
  Description: Imię po zastosowaniu normalizacji

Field: details.duration
  Type: string
  Description: Czas potrzebny serwerowi na przetworzenie zapytania

Field: result_found
  Type: bool
  Description: Prawda jeżeli byliśmy w stanie uzyskać informacje o płci na podstawie podanego imienia

Field: email
  Type: string
  Description: Adres e-mail użyty do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (między 0 a 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik twojego zapytania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: mężczyzna, kobieta, nieznana

--- 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 <twój token autoryzacyjny> link' \
  -d '{"email":"theresa.miller14@gmail.com"}'

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

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Pobierz kraj pochodzenia (v2)
PURPOSE: Odkryj prawdopodobny kraj pochodzenia i tło etniczne na podstawie imion.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <twój token autoryzacyjny> 
link

--- REQUEST PARAMETERS ---

Parameter: first_name
  Type: string
  Required: REQUIRED
  Description: Imię do wyszukania

Parameter: full_name
  Type: string
  Required: OPTIONAL
  Description: Pełne imię i nazwisko do sprawdzenia. Można podać zamiast pola first_name

Parameter: email
  Type: string
  Required: OPTIONAL
  Description: Adres e-mail, który można podać zamiast pola "imię"

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksymalnie 50 znaków. Id może być ustawione na dowolną alfanumeryczną wartość.
            Na przykład możesz ustawić id na swoje wewnętrzne id zbioru danych w bazie danych. W asynchronicznym 
            środowisku może to pomóc w lepszym połączeniu odpowiedzi z poprzednim żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie poprzez imię
Request Body (JSON):
{
    "first_name": "Johann"
}

Example 2: Zapytania według pełnego nazwiska
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 3: Wyszukaj po adresie e-mail
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: Wysłany payload

Field: details.credits_used
  Type: int
  Description: Ilość użytych zapytań dla tej zapytania

Field: details.samples
  Type: int
  Description: Liczba rekordów znalezionych w naszej bazie danych, które pasują do twojego zapytania

Field: details.country
  Type: string
  Description: Znalezione przez nas kraj

Field: details.first_name_sanitized
  Type: string
  Description: Imię po zastosowaniu normalizacji

Field: details.duration
  Type: string
  Description: Czas potrzebny serwerowi na przetworzenie zapytania

Field: result_found
  Type: bool
  Description: Prawda jeżeli byliśmy w stanie uzyskać informacje o płci na podstawie podanego imienia

Field: country_of_origin_map_url
  Type: string
  Description: URL do interaktywnej mapy związanej z tym imieniem

Field: first_name
  Type: string
  Description: Imię, które było użyte do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (między 0 a 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wyniki dotyczące płci są 100% dokładne

Field: gender
  Type: string
  Description: Możliwe wartości: mężczyzna, kobieta, nieznana

Field: country_of_origin
  Type: object
  Description: Top 25 krajów pochodzenia. Zobacz "Pełną Listę Możliwych Krajów" dla listy obsługiwanych krajów. Każdy rekord zawiera pola country_name, country, probability, continental_region i statistical_region

Field: language_of_origin
  Type: string
  Description: Język pochodzenia tego imienia

Field: meaning
  Type: string
  Description: Krótki opis znaczenia tego imienia

Field: ethnicity
  Type: object
  Description: Pole "etniczność" dostarcza szczegółów na temat głównej grupy etnicznej związanej z imieniem, a także jak imię jest rozłożone pomiędzy różne grupy etniczne

Field: ethnicity.id
  Type: string
  Description: Pole id zawiera identyfikator określonej głównej grupy etnicznej. Zobacz "Kompletną listę możliwych grup etnicznych" dla pełnej listy możliwych grup etnicznych

Field: ethnicity.name
  Type: string
  Description: Pole zawiera nazwę określonej głównej grupy etnicznej. Zobacz "Kompletna lista możliwych grup etnicznych" dla pełnej listy możliwych grup etnicznych

Field: ethnicity.distribution
  Type: array
  Description: Pole Distribution zawiera informacje na temat proporcji imienia w różnych grupach etnicznych. Każdy wpis w tablicy zawiera pola id (tekst), name (tekst) i percentage (liczba rzeczywista). Zobacz "Kompletną Listę Możliwych Grup Etnicznych" aby uzyskać pełną listę możliwych wartoś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 POST \
  'https://gender-api.com/v2/country-of-origin' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <twój token autoryzacyjny> link' \
  -d '{"first_name":"Johann"}'

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

=== END OF INSTRUCTIONS ===

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Pobierz statystyki (v2)
PURPOSE: Pobierz szczegółowe statystyki użycia i sprawdź pozostałe kredyty zapytań na swoim koncie.

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

--- AUTHENTICATION ---
Header: Content-Type: application/json
Header: Authorization: Bearer <twój token autoryzacyjny> 
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: Zwraca prawdę, jeśli nie ma więcej żądań

Field: remaining_credits
  Type: int
  Description: Liczba pozostałych żądań

Field: details.credits_used
  Type: int
  Description: Ilość użytych zapytań dla tej zapytania

Field: details.duration
  Type: string
  Description: Czas potrzebny serwerowi na przetworzenie zapytania

Field: usage_last_month.date
  Type: string
  Description: Data ostatniego miesiąca

Field: usage_last_month.credits_used
  Type: int
  Description: Żądania, których użyłeś w ciągu ostatniego miesiąca

--- 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 <twój token autoryzacyjny> link' \

=== END OF INSTRUCTIONS ===