Nimien, sähköpostiosoitteiden ja käyttäjänimien eräennusteet

Nimien, sähköpostiosoitteiden ja käyttäjänimien eräpyyntö

Parametri	Tyyppi	Pakollinen	Oletusarvo	Kuvaus
`items`	`array<object>`	Kyllä	`—`	1–50 ennustekohdetta; IP-kokeilussa enintään 10. Tulokset säilyttävät syötteiden järjestyksen.
`items[].type`	`string`	Kyllä	`—`	Syötteen luokka: name, email tai username.
`items[].value`	`string`	Kyllä	`—`	Pakollinen. 1–254 merkkiä; ei saa olla tyhjä eikä sisältää ohjausmerkkejä. Sähköpostiarvon on oltava syntaksiltaan kelvollinen sähköpostiosoite.
`items[].country`	`string`	Ei	`—`	Valinnainen ISO 3166-1 alpha-2 -koodi isoilla kirjaimilla, esimerkiksi TR tai US. Maakohtainen haku voi siirtyä käyttämään globaalia tietoaineistoa.
`items[].forceToGenderize`	`boolean`	Ei	`false`	Hakee ensin tietoaineistosta ja sitten tarvittaessa lempinimiä tulkitsevalla tekoälyllä. Tuettu tyypeille name, email ja username.
`items[].options`	`object`	Ei	`—`	Kunkin syötteen tekoälyasetukset sisältävä objekti.
`items[].options.ai_mode`	`string`	Ei	`off`	Sallitut arvot: off, fallback, always. Kun forceToGenderize: true, jätä kenttä pois tai käytä fallback-arvoa.
`items[].id`	`string`	Ei	`—`	Valinnainen 1–64 merkin tunniste POST-pyynnön JSON-rungossa. Palautetaan kunkin erätuloksen yhteydessä, ja sen on oltava yksilöllinen erän sisällä. Yksittäisissä ennusteissa se hyväksytään, mutta sitä ei palauteta. Ei tuettu GET-kyselyissä.

POST /gender/batch hyväksyy items-taulukon, jossa on 1–50 kohdetta API-avaimella tai enintään 10 kohdetta IP-kokeilussa. Voit lähettää pelkkiä nimiä, pelkkiä sähköpostiosoitteita, pelkkiä käyttäjänimiä tai kaikkia kolmea sekaisin. Jokaisella kohteella on omat country-, forceToGenderize- ja options-kentät. Tunnisteet ovat valinnaisia, mutta niiden on oltava yksilöllisiä.

Tulokset säilyttävät syötteiden järjestyksen, ja kukin tulos sisältää kentät index ja charged_credits, valinnaisen id-tunnisteesi sekä täsmälleen toisen kentistä data tai error. HTTP 200 voi sisältää kohdekohtaisia virheitä, joten tarkista jokainen kohde. meta.summary ilmoittaa arvot total, succeeded, identified, unknown ja failed. Tuntematon ennuste on onnistunut ja laskutettava kohde.

Jos pyynnön validointi tai suunnittelu epäonnistuu, koko erä hylätään ennen veloitusta. Jos jokainen suoritettu kohde epäonnistuu, API palauttaa muun kuin 2xx-tilan Problem-vastauksen, jossa on data-taulukko ja vanha results-alias. Epäonnistuneet kohteet maksavat nolla krediittiä vahvistetun palautuksen jälkeen. Jos laskutusta ei ole vahvistettu, älä oleta kohteiden veloituksia lopullisiksi.

Valitse ohjelmointikieli. Määritä API-avain, suorita sitten esimerkki palvelimellasi.

Jokainen ennustepyyntö on uusi laskutettava toiminto, myös uudelleenyritys. Nämä esimerkit eivät yritä uudelleen automaattisesti. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä.

Ennen suorittamista: käyttöoikeus ja virheiden käsittely

Suorita esimerkit palvelimellasi. Aseta prosessin ympäristömuuttujan GENDERAPI_API_KEY arvoksi nykyinen API-avaimesi. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi siirtää pyynnön IP-kokeiluun.

HTTP 4xx- ja 5xx-JSON-vastauksissa esimerkit säilyttävät virherungon ja palauttavat nollasta poikkeavan poistumiskoodin. Tarkista code, action ja meta.usage.billing_status ennen uutta yritystä. Tarkista HTTP 200 -eräpyyntövastauksissa lisäksi kunkin kohteen data tai error.

Virhe- ja uudelleenyritysopas →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Laura",
      "country": "FI"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ POSIX-komentotulkissa. Suorita päätteessä. Suoritusympäristön dokumentaatio

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Laura",
      "country": "FI"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; sisäänrakennettu fetch. Tallenna nimellä example.mjs ja suorita node example.mjs. Suoritusympäristön dokumentaatio

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Laura\",\"country\":\"FI\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender/batch",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; standardikirjasto. Tallenna nimellä example.py ja suorita python3 example.py. Suoritusympäristön dokumentaatio

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Laura","country":"FI"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita php example.php. Suoritusympäristön dokumentaatio

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Laura\",\"country\":\"FI\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender/batch"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; standardikirjaston HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita java GenderApiExample.java. Suoritusympäristön dokumentaatio

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Laura\",\"country\":\"FI\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

.NET 8+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten dotnet run. Suoritusympäristön dokumentaatio

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Laura\",\"country\":\"FI\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; standardikirjasto. Tallenna nimellä main.go ja suorita go run main.go. Suoritusympäristön dokumentaatio

Eräpyynnön vastauksen tulkinta

Tämä esimerkki yhdistää kaksi 1. lokakuuta 2026 haettua todellista tulosta, tietoaineisto-osuman ja tuntemattoman tuloksen, havainnollistavaan palveluntarjoajan virheeseen. Se havainnollistaa osittain onnistunutta HTTP 200 -vastausta, ei yllä olevan eräpyynnön odotettua tulosta. Kaksi onnistunutta kohdetta maksavat 1 krediitin kumpikin; epäonnistuneen kohteen veloitus on vahvistetusti nolla.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Laura",
          "country": "FI"
        },
        "name": "laura",
        "gender": "female",
        "country": "FI",
        "confidence": 0.9966887417218543,
        "confidence_kind": "observed_frequency",
        "sample_count": 906,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "laura",
          "method": "normalized",
          "scope": "country",
          "country": "FI"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 2,
      "remaining_credits": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}

Erätulosten kentät

Kenttä	Tyyppi	Voi olla null	Esimerkki	Kuvaus
`data`	`array<object>`	Ei	`[…]`	Järjestetyt tulokset. Kukin kohde sisältää ennusteen tai virheen; tarkista kaikki.
`data[].index`	`integer`	Ei	`0`	Sijainti lähetetyssä items-taulukossa nollasta alkaen.
`data[].id`	`string`	Ei	`"contact-1"`	Oma syötetunnisteesi; mukana vain, jos annoit sen.
`data[].charged_credits`	`integer`	Ei	`1`	Kohteen nettoveloitus vahvistettujen palautusten jälkeen. Ei lopullinen, jos kokonaisveloitusta ei ole vahvistettu.
`data[].data`	`object`	Ei	`{…}`	Mukana onnistuneelle kohteelle, myös tuntemattomalle tulokselle. Käyttää vastausoppaassa kuvattuja ennustekenttiä.
`data[].error`	`object`	Ei	`{…}`	Mukana epäonnistuneelle kohteelle data-kentän sijaan. Käyttää virheoppaassa kuvattuja Problem Details -kenttiä.

Erän yhteenvedon kentät

Kenttä	Tyyppi	Voi olla null	Esimerkki	Kuvaus
`meta.summary.total`	`integer`	Ei	`3`	Erän kohteiden kokonaismäärä.
`meta.summary.succeeded`	`integer`	Ei	`2`	Onnistuneet kohteet, myös tuntemattomat ennusteet.
`meta.summary.identified`	`integer`	Ei	`1`	Onnistuneet kohteet, joiden sukupuoli ei ole null.
`meta.summary.unknown`	`integer`	Ei	`1`	Onnistuneet kohteet, joiden sukupuoli on null; nämä tulokset veloitetaan.
`meta.summary.failed`	`integer`	Ei	`1`	Epäonnistuneet kohteet. total = succeeded + failed; succeeded = identified + unknown.

Käyttöoikeus, veloitus ja pyynnön metatiedot

Kenttä	Tyyppi	Voi olla null	Esimerkki	Kuvaus
`meta.request_id`	`string`	Ei	`"550e8400-e29b-41d4-a716-446655440000"`	Tämän HTTP-yrityksen yksilöllinen tunniste; myös X-Request-ID-otsakkeessa.
`meta.duration_ms`	`integer`	Ei	`42`	Pyynnön käsittelyaika millisekunteina.
`meta.access.mode`	`string`	Ei	`"api_key"`	api_key, ip_trial tai unauthenticated. Tarkista api_key käyttäessäsi maksullista tiliä.
`meta.access.reason`	`string`	Kyllä	`null`	Kokeiluun siirtymisen syy: api_key_missing, api_key_invalid tai api_key_not_found; muuten null.
`meta.usage.charged_credits`	`integer`	Kyllä	`1`	Veloitetut nettokrediitit. Nolla ennen veloitusta tai vahvistetun täyden palautuksen jälkeen; null, jos veloitusta ei ole vahvistettu.
`meta.usage.remaining_credits`	`integer`	Kyllä	`99`	Saldo toiminnon valmistuessa. Voi olla negatiivinen; null, jos saldoa ei saada tai veloitusta ei ole vahvistettu.
`meta.usage.billing_status`	`string`	Ei	`"confirmed"`	not_charged, confirmed tai unconfirmed. Tarkista ennen epäonnistuneen ennusteen uutta yritystä.
`meta.usage.resets_at`	`string`	Kyllä	`"2026-09-27T12:00:00.000Z"`	IP-kokeilun nollausaika UTC-ajassa (ISO 8601); null API-avaintileillä tai jos aika ei ole tiedossa.
`meta.usage.limit`	`integer`	Kyllä	`10`	IP-kokeilun krediittikiintiö; null API-avaintileille.
`meta.usage.period_seconds`	`integer`	Kyllä	`86400`	IP-kokeilujakson pituus sekunteina; null API-avaintileille.

Suunnittele erän krediitit ja uudelleenyritykset

Todenna pyyntö nykyisellä API-avaimellasi Bearer-otsakkeessa ja lähetä Content-Type: application/json. Jokainen lähetetty erä on uusi toiminto. Jos yrität osittain epäonnistunutta erää uudelleen, lähetä laskutuksen tarkistamisen jälkeen vain epäonnistuneet kohteet; onnistuneiden kohteiden uudelleenlähetys veloittaa ne uudelleen.

Eräpyynnön kohteissa tekoäly on oletuksena pois (off), ja kukin onnistunut kohde maksaa 1 krediitin. Erikseen valittu fallback maksaa myös yhteensä 1 krediitin tekoäly mukaan lukien; always maksaa 2. forceToGenderize maksaa 1 krediitin tietoaineistosta ratkaistusta tuloksesta tai yhteensä 2, jos tekoälyä käytetään. Myös onnistuneet tuntemattomat tulokset veloitetaan. Yksi krediitti alkusaldona riittää erän aloittamiseen; lopullinen veloitus voi jättää saldon negatiiviseksi.

Käsittele yhteystietoluettelo niin, että jokainen rivi pysyy tallessa

Eräpyyntöjen päätepiste käsittelee luettelot, joissa on pelkkiä nimiä, pelkkiä sähköpostiosoitteita tai molempia sekaisin. Jaa API-avaimella tehtävä ajo enintään 50 kohteen eriin; IP-kokeilu sallii enintään 10 kohdetta pyyntöä kohden. Pidä itse kirjaa ajon etenemisestä ja anna jokaiselle kohteelle id, joka on yksilöllinen erän sisällä. Palautettu index lasketaan nollasta lähetetyn erän sisällä, ei koko yhteystietoluettelossa.

Vaihe	Mitä tallennetaan tai tarkistetaan	Miksi sillä on merkitystä
1. Valmistele jokainen erä	Säilytä lähderivi ja kohteen id; aseta country ja tekoälyasetukset kohdekohtaisesti.	Älä oleta, että nimi on yksilöllinen kaikkien yhteystietojen joukossa.
2. Lue koko vastaus	Tallenna meta.request_id ja yhdistä jokainen data[]-tietue id- tai index-arvon avulla.	HTTP 200 voi sisältää sekä onnistuneita ennusteita että kohdekohtaisia virheitä.
3. Tallenna onnistuneet tulokset	Säilytä sekä tunnistetut että tuntemattomat ennusteet, myös JSON null -arvot ja perustekentät.	Tuntematon tulos on valmis ja laskutettava tulos; se ei ole epäonnistunut rivi, jota yritetään automaattisesti uudelleen.
4. Täsmäytä virheet ja krediitit	Tarkista jokainen error ja meta.usage.billing_status ennen kuin päätät uudesta pyynnöstä.	Kun laskutus on vahvistettu, yritä uudelleen vain epäonnistuneita kohteita, joiden virhe sitä edellyttää. Onnistuneet kohteet veloitettaisiin uudelleen.
5. Keskeytä epävarmat uudelleenyritykset	Säilytä pyynnön tunniste, jos laskutusta ei ole vahvistettu tai verkkovirhe jättää tuloksen epäselväksi.	Älä lähetä koko erää uudelleen sokeasti; noudata ensin virheitä ja laskutusta koskevia ohjeita.

Valitse päättelytapa jokaiselle yhteystiedolle

Tämä suoritettava pyyntö käyttää kolmea eri käytäntöä: vain tietoaineistoa koko nimelle, tavallista tekoälyä varalla sähköpostiosoitteelle ja lempinimiä tulkitsevaa tekoälyä varalla käyttäjänimelle. Kyse on esimerkkisyötteestä, ei lupauksesta, että kaikille kolmelle yhteystiedolle saadaan sukupuoli. Valitse ohjelmointikieli koodin yläpuolelta ja aseta GENDERAPI_API_KEY ennen suorittamista.

Ilman forceToGenderize-asetusta eräpyynnön kohteissa tekoäly on oletuksena pois (off), toisin kuin yksittäisissä hauissa. Aseta fallback erikseen, jos haluat käyttää tavallista tekoälyä varalla. Sekä off että tavallinen fallback maksavat 1 krediitin onnistunutta kohdetta kohden; always ohittaa tietoaineiston ja maksaa 2. forceToGenderize maksaa 1 krediitin tietoaineistosta ratkaistusta tuloksesta tai yhteensä 2, jos tekoälyä käytetään. Myös onnistuneet tuntemattomat tulokset veloitetaan. Älä yhdistä forceToGenderize-asetusta tiloihin off tai always.