DOKUMENTACJA API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Zarejestruj się (v2)
PURPOSE: Załóż darmowe konto i otrzymaj hasło do logowania oraz token API. Bez konieczności uwierzytelniania.

--- 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: Adres e-mail do rejestracji. Imię ani nazwisko nie są wymagane.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Musi mieć wartość true. Użytkownik musi zaakceptować Regulamin oraz Politykę prywatności.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Zapis do newslettera. Domyślnie false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Język konta. Jeden z: en, de, es. Domyślnie: en.

--- REQUEST EXAMPLES ---

Example 1: Zarejestruj się za pomocą adresu e-mail
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Zarejestruj się i zasubskrybuj 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: Zarejestrowany adres e-mail.

Field: password
  Type: string
  Description: Losowe hasło logowania do panelu w przeglądarce. Zostanie zwrócone tylko raz — zapisz je w bezpiecznym miejscu. Użytkownik może później zresetować je przez procedurę „nie pamiętam hasła”.

Field: api_token
  Type: string
  Description: Token bearer do API. Użyj go jako „Authorization: Bearer ” w żądaniach /v2/…. Zacznie działać, gdy użytkownik potwierdzi swój adres e-mail.

Field: free_requests_per_month
  Type: int
  Description: Liczba bezpłatnych żądań przyznawanych na miesiąc.

Field: status
  Type: string
  Description: Status konta. „awaiting_activation”, dopóki adres e-mail nie zostanie potwierdzony.

Field: message
  Type: string
  Description: Czytelna wskazówka, co zrobić dalej (potwierdzić adres e-mail).

Field: docs_url
  Type: string
  Description: Link do gotowych do użycia instrukcji wdrożenia AI (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 sprawdzenia

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

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Ustawienia regionalne 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żesz ustawić na dowolną wartość alfanumeryczną.
Możesz na przykład wpisać tu swój wewnętrzny identyfikator zbioru danych w bazie. W środowisku asynchronicznym pomoże Ci to lepiej powiązać odpowiedź z wcześniejszym żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie tylko po imieniu
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 regionalnych przeglądarki
Request Body (JSON):
{
    "first_name": "Sandra",
    "locale": "en_US"
}

Example 4: Zapytanie po imieniu z użyciem adresu IP do lokalizacji
Request Body (JSON):
{
    "first_name": "Sandra",
    "ip": "54.201.16.177"
}

Example 5: Zapytanie o wiele imion 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: Liczba żądań wykorzystanych na to zapytanie

Field: details.samples
  Type: int
  Description: Liczba rekordów w naszej bazie danych, które pasują do Twojego żądania

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

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

Field: details.duration
  Type: string
  Description: Czas, jakiego serwer potrzebował na przetworzenie żądania

Field: result_found
  Type: bool
  Description: true, jeśli udało nam się ustalić płeć dla podanego imienia

Field: first_name
  Type: string
  Description: Imię, którego użyliśmy do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (od 0 do 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik Twojego żądania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: male, female, unknown

--- 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 i nazwisku (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 sprawdzenia

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

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Ustawienia regionalne 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żesz ustawić na dowolną wartość alfanumeryczną.
Możesz na przykład wpisać tu swój wewnętrzny identyfikator zbioru danych w bazie. W środowisku asynchronicznym pomoże Ci to lepiej powiązać odpowiedź z wcześniejszym żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie tylko po pełnym imieniu i nazwisku
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

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

Example 3: Zapytanie po pełnym imieniu i nazwisku oraz ustawieniach regionalnych przeglądarki
Request Body (JSON):
{
    "full_name": "Thomas Johnson",
    "locale": "en_US"
}

Example 4: Zapytanie po pełnym imieniu i nazwisku z użyciem adresu IP do lokalizacji
Request Body (JSON):
{
    "full_name": "Markus Stefan NonExistingLastName",
    "ip": "54.201.16.177"
}

Example 5: Zapytanie o wiele imion 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: Liczba żądań wykorzystanych na to zapytanie

Field: details.samples
  Type: int
  Description: Liczba rekordów w naszej bazie danych, które pasują do Twojego żądania

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

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

Field: details.duration
  Type: string
  Description: Czas, jakiego serwer potrzebował na przetworzenie żądania

Field: result_found
  Type: bool
  Description: true, jeśli udało nam się ustalić płeć dla podanego imienia

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

Field: probability
  Type: float
  Description: Ta wartość (od 0 do 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik Twojego żądania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: male, female, unknown

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

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

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Ustawienia regionalne 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żesz ustawić na dowolną wartość alfanumeryczną.
Możesz na przykład wpisać tu swój wewnętrzny identyfikator zbioru danych w bazie. W środowisku asynchronicznym pomoże Ci to lepiej powiązać odpowiedź z wcześniejszym żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie tylko po adresie e-mail
Request Body (JSON):
{
    "email": "theresa.miller14@gmail.com"
}

Example 2: Zapytanie po adresie e-mail i kodzie kraju
Request Body (JSON):
{
    "email": "thomas.clarks@hotmail.com",
    "country": "US"
}

Example 3: Zapytanie po adresie e-mail i ustawieniach regionalnych przeglądarki
Request Body (JSON):
{
    "email": "Thomas.j32@live.com",
    "locale": "en_US"
}

Example 4: Zapytanie po adresie e-mail z użyciem adresu IP do lokalizacji
Request Body (JSON):
{
    "email": "thomasfromnewyork@gmail.com",
    "ip": "54.201.16.177"
}

Example 5: Zapytanie o wiele imion 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: Liczba żądań wykorzystanych na to zapytanie

Field: details.samples
  Type: int
  Description: Liczba rekordów w naszej bazie danych, które pasują do Twojego żądania

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

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

Field: details.duration
  Type: string
  Description: Czas, jakiego serwer potrzebował na przetworzenie żądania

Field: result_found
  Type: bool
  Description: true, jeśli udało nam się ustalić płeć dla podanego imienia

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

Field: probability
  Type: float
  Description: Ta wartość (od 0 do 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wynik Twojego żądania o płeć jest w 100% dokładny.

Field: gender
  Type: string
  Description: Możliwe wartości: male, female, unknown

--- 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 do sprawdzenia. Można go podać zamiast pola first_name

Parameter: id
  Type: string
  Required: OPTIONAL
  Description: Maksymalnie 50 znaków. Id możesz ustawić na dowolną wartość alfanumeryczną.
Możesz na przykład wpisać tu swój wewnętrzny identyfikator zbioru danych w bazie. W środowisku asynchronicznym pomoże Ci to lepiej powiązać odpowiedź z wcześniejszym żądaniem

--- REQUEST EXAMPLES ---

Example 1: Zapytanie po imieniu
Request Body (JSON):
{
    "first_name": "Johann"
}

Example 2: Zapytanie po pełnym imieniu i nazwisku
Request Body (JSON):
{
    "full_name": "Theresa Miller"
}

Example 3: Zapytanie 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: Liczba żądań wykorzystanych na to zapytanie

Field: details.samples
  Type: int
  Description: Liczba rekordów w naszej bazie danych, które pasują do Twojego żądania

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

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

Field: details.duration
  Type: string
  Description: Czas, jakiego serwer potrzebował na przetworzenie żądania

Field: result_found
  Type: bool
  Description: true, jeśli udało nam się ustalić płeć dla 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órego użyliśmy do określenia płci

Field: probability
  Type: float
  Description: Ta wartość (od 0 do 1) określa wiarygodność naszej bazy danych. Wartość 1 oznacza, że wyniki Twojego żądania o płeć są w 100% dokładne

Field: gender
  Type: string
  Description: Możliwe wartości: male, female, unknown

Field: country_of_origin
  Type: object
  Description: Top 25 krajów pochodzenia. Zobacz „Pełna lista możliwych krajów”, aby poznać listę 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 ethnicity zawiera szczegóły dotyczące głównej grupy etnicznej powiązanej z imieniem oraz informację o tym, jak imię rozkłada się pomiędzy różne grupy etniczne

Field: ethnicity.id
  Type: string
  Description: Pole id zawiera identyfikator ustalonej głównej grupy etnicznej. Zobacz „Pełna lista możliwych grup etnicznych”, aby poznać pełną listę możliwych grup etnicznych

Field: ethnicity.name
  Type: string
  Description: Pole name zawiera nazwę ustalonej głównej grupy etnicznej. Zobacz „Pełna lista możliwych grup etnicznych”, aby poznać pełną listę możliwych grup etnicznych

Field: ethnicity.distribution
  Type: array
  Description: Pole Distribution zawiera informacje o udziale imienia w poszczególnych grupach etnicznych. Każdy wpis tablicy zawiera pola id (string), name (string) i percentage (float). Zobacz „Pełna lista możliwych grup etnicznych”, aby poznać 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 żądań 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 true, jeśli nie zostało już żadne żądanie

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

Field: details.credits_used
  Type: int
  Description: Liczba żądań wykorzystanych na to zapytanie

Field: details.duration
  Type: string
  Description: Czas, jakiego serwer potrzebował na przetworzenie żądania

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