Gbif

GBIF name normalization helpers.

Functions:

Name	Description
normalize_spezies	Resolve a scientific name to GBIF's canonical name.
normalize_spezies_batch	Resolve multiple scientific names in one GBIF request.

normalize_spezies(name, min_confidence=None, query_param=DEFAULT_QUERY_PARAM, response_fields=None)

Resolve a species name to GBIF's canonical name.

Parameters:

Name	Type	Description	Default
name	str	Species name to resolve.	required
min_confidence	int | None	Optional minimum GBIF match confidence percentage required to return a name.	None
query_param	str	Query parameter name used to send name to GBIF.	DEFAULT_QUERY_PARAM
response_fields	list[str] | None	List of GBIF response fields to return. If not provided, all fields will be returned.	None

Returns:

Type	Description
dict[str, Any] | None	A dictionary containing the requested GBIF response fields, or None if no match is found or the
dict[str, Any] | None	match does not meet min_confidence.

Raises:

Type	Description
ValueError	If min_confidence is not between 0 and 100, inclusive.
ValueError	If GBIF returns an invalid match response.
RequestException	If the GBIF Species Match API request fails.
HTTPError	If the GBIF Species Match API returns a non-200 status code.

Source code in src/kibad_llm/normalization/gbif.py

def normalize_spezies(
    name: str,
    min_confidence: int | None = None,
    query_param: str = DEFAULT_QUERY_PARAM,
    response_fields: list[str] | None = None,
) -> dict[str, Any] | None:
    """Resolve a species name to GBIF's canonical name.

    Args:
        name: Species name to resolve.
        min_confidence: Optional minimum GBIF match confidence percentage required to return a name.
        query_param: Query parameter name used to send `name` to GBIF.
        response_fields: List of GBIF response fields to return. If not provided, all fields will be returned.

    Returns:
        A dictionary containing the requested GBIF response fields, or `None` if no match is found or the
        match does not meet `min_confidence`.

    Raises:
        ValueError: If `min_confidence` is not between 0 and 100, inclusive.
        ValueError: If GBIF returns an invalid match response.
        requests.RequestException: If the GBIF Species Match API request fails.
        requests.HTTPError: If the GBIF Species Match API returns a non-200 status code.
    """
    _validate_min_confidence(min_confidence)

    response = requests.get(
        GBIF_SPECIES_MATCH_URL,
        params={query_param: name},
        timeout=10,
    )
    response.raise_for_status()
    result = response.json()

    return _normalize_match_result(result, min_confidence, response_fields)

normalize_spezies_batch(names, min_confidence=None, query_param=DEFAULT_QUERY_PARAM, response_fields=None)

Resolve scientific names to GBIF's canonical names in one request.

Parameters:

Name	Type	Description	Default
names	list[str]	Scientific names to resolve. GBIF accepts up to 1,000 names per request.	required
min_confidence	int | None	Optional minimum GBIF match confidence percentage required to return a name.	None
query_param	str	Request-object field name used to send each scientific name to GBIF.	DEFAULT_QUERY_PARAM
response_fields	list[str] | None	List of GBIF response fields to return. If empty, all fields will be returned.	None

Returns:

Type	Description
list[dict[str, Any] | None]	A list of dictionaries containing the requested GBIF response fields, or None for names that
list[dict[str, Any] | None]	have no match or do not meet min_confidence. The order of the returned list matches the order of
list[dict[str, Any] | None]	the input names.

Raises:

Type	Description
ValueError	If min_confidence is not between 0 and 100, inclusive.
ValueError	If GBIF returns an invalid batch match response.
RequestException	If the GBIF Species Match API request fails.
HTTPError	If the GBIF Species Match API returns a non-200 status code.

Source code in src/kibad_llm/normalization/gbif.py

def normalize_spezies_batch(
    names: list[str],
    min_confidence: int | None = None,
    query_param: str = DEFAULT_QUERY_PARAM,
    response_fields: list[str] | None = None,
) -> list[dict[str, Any] | None]:
    """Resolve scientific names to GBIF's canonical names in one request.

    Args:
        names: Scientific names to resolve. GBIF accepts up to 1,000 names per request.
        min_confidence: Optional minimum GBIF match confidence percentage required to return a name.
        query_param: Request-object field name used to send each scientific name to GBIF.
        response_fields: List of GBIF response fields to return. If empty, all fields will be returned.

    Returns:
        A list of dictionaries containing the requested GBIF response fields, or `None` for names that
        have no match or do not meet `min_confidence`. The order of the returned list matches the order of
        the input `names`.

    Raises:
        ValueError: If `min_confidence` is not between 0 and 100, inclusive.
        ValueError: If GBIF returns an invalid batch match response.
        requests.RequestException: If the GBIF Species Match API request fails.
        requests.HTTPError: If the GBIF Species Match API returns a non-200 status code.
    """
    if len(names) > 1000:
        raise ValueError(
            f"Too many Scientific names to resolve ({len(names)}). GBIF accepts up to 1,000 names per request."
        )

    _validate_min_confidence(min_confidence)

    response = requests.post(
        GBIF_SPECIES_BATCH_MATCH_URL,
        json=[{query_param: name} for name in names],
        timeout=10,
    )
    response.raise_for_status()
    results = response.json()

    if not isinstance(results, list) or len(results) != len(names):
        raise ValueError("GBIF returned an invalid batch match response")

    return [_normalize_match_result(result, min_confidence, response_fields) for result in results]

add_arguments(parser)

Add GBIF Species Match API options to a command-line parser.

Source code in src/kibad_llm/normalization/gbif.py

def add_arguments(parser: argparse.ArgumentParser) -> None:
    """Add GBIF Species Match API options to a command-line parser."""
    parser.add_argument(
        "--min-confidence",
        type=int,
        default=None,
        help="Minimum GBIF match confidence percentage required to return a name.",
    )
    parser.add_argument(
        "--query-param",
        default=DEFAULT_QUERY_PARAM,
        help="Query parameter name used to send the species name to GBIF.",
    )
    parser.add_argument(
        "--response-fields",
        default=None,
        nargs="+",
        help="GBIF response fields returned from the GBIF Species Match API. If not provided, "
        "all fields will be returned. Entries can contain '.' to access nested fields, "
        "e.g. 'classification.GENUS'.",
    )

create_normalizer(arguments)

Create a GBIF normalizer from parsed command-line arguments.

Source code in src/kibad_llm/normalization/gbif.py

def create_normalizer(arguments: argparse.Namespace) -> Callable[[str], dict[str, Any] | None]:
    """Create a GBIF normalizer from parsed command-line arguments."""
    logger.info(
        f"Creating GBIF normalizer with query_param={arguments.query_param}, "
        f"response_fields={arguments.response_fields}, and min_confidence={arguments.min_confidence}"
    )
    return partial(
        normalize_spezies,
        min_confidence=arguments.min_confidence,
        query_param=arguments.query_param,
        response_fields=arguments.response_fields,
    )