# This file was auto-generated by Fern from our API Definition.

import typing

import pydantic
from ..core.pydantic_utilities import IS_PYDANTIC_V2, UniversalBaseModel


class GeoTarget(UniversalBaseModel):
    """
    Granular geographic targeting for proxy selection.

    Supports country, subdivision (state/region), and city level targeting.
    Uses ISO 3166-1 alpha-2 for countries, ISO 3166-2 for subdivisions,
    and GeoNames English names for cities.

    Examples:
        - {"country": "US"} - United States (same as RESIDENTIAL)
        - {"country": "US", "subdivision": "CA"} - California, US
        - {"country": "US", "subdivision": "NY", "city": "New York"} - New York City
        - {"country": "GB", "city": "London"} - London, UK
    """

    country: str = pydantic.Field()
    """
    ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
    """

    subdivision: typing.Optional[str] = pydantic.Field(default=None)
    """
    ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
    """

    city: typing.Optional[str] = pydantic.Field(default=None)
    """
    City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
    """

    if IS_PYDANTIC_V2:
        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
    else:

        class Config:
            frozen = True
            smart_union = True
            extra = pydantic.Extra.allow
