suggest

gurume.suggest

地區建議功能

AreaSuggestion dataclass

AreaSuggestion(
    name: str,
    datatype: str,
    id_in_datatype: int,
    lat: float | None = None,
    lng: float | None = None,
)

地區建議

KeywordSuggestion dataclass

KeywordSuggestion(
    name: str,
    datatype: str,
    id_in_datatype: int | str,
    lat: float | None = None,
    lng: float | None = None,
)

關鍵字建議

TabelogSuggestUnavailableError

Bases: RuntimeError

Raised when Tabelog's suggest API returns no data (upstream endpoint change).

get_area_suggestions

get_area_suggestions(
    query: str, timeout: float = 10.0
) -> list[AreaSuggestion]

取得地區建議

Parameters:

Name	Type	Description	Default
query	str	搜尋關鍵字	required
timeout	float	請求超時時間（秒）	10.0

Returns:

Type	Description
list[AreaSuggestion]	地區建議列表

Source code in src/gurume/suggest.py

def get_area_suggestions(query: str, timeout: float = 10.0) -> list[AreaSuggestion]:
    """取得地區建議

    Args:
        query: 搜尋關鍵字
        timeout: 請求超時時間（秒）

    Returns:
        地區建議列表
    """
    if not query or not query.strip():
        return []

    params = {"sa": query.strip()}

    try:
        resp = httpx.get(
            url=SUGGEST_URL,
            params=params,
            headers=_build_headers(),
            timeout=timeout,
            follow_redirects=True,
        )
        resp.raise_for_status()
        data = resp.json()
        if isinstance(data, dict) and data.get("suggest_empty"):
            raise TabelogSuggestUnavailableError(TabelogSuggestUnavailableError.HELP)
        if not isinstance(data, list):
            return []
    except TabelogSuggestUnavailableError:
        raise
    except (httpx.HTTPError, ValueError):
        return []
    else:
        return _parse_area_suggestions(data)

get_area_suggestions_async async

get_area_suggestions_async(
    query: str, request_timeout: float = 10.0
) -> list[AreaSuggestion]

取得地區建議（異步版本）

Parameters:

Name	Type	Description	Default
query	str	搜尋關鍵字	required
request_timeout	float	請求超時時間（秒）	10.0

Returns:

Type	Description
list[AreaSuggestion]	地區建議列表

Source code in src/gurume/suggest.py

async def get_area_suggestions_async(query: str, request_timeout: float = 10.0) -> list[AreaSuggestion]:
    """取得地區建議（異步版本）

    Args:
        query: 搜尋關鍵字
        request_timeout: 請求超時時間（秒）

    Returns:
        地區建議列表
    """
    if not query or not query.strip():
        return []

    params = {"sa": query.strip()}

    try:
        async with httpx.AsyncClient(timeout=request_timeout, follow_redirects=True) as client:
            resp = await client.get(url=SUGGEST_URL, params=params, headers=_build_headers())
            resp.raise_for_status()
            data = resp.json()
            if isinstance(data, dict) and data.get("suggest_empty"):
                raise TabelogSuggestUnavailableError(TabelogSuggestUnavailableError.HELP)
            if not isinstance(data, list):
                return []
    except TabelogSuggestUnavailableError:
        raise
    except (httpx.HTTPError, ValueError):
        return []
    else:
        return _parse_area_suggestions(data)

get_keyword_suggestions

get_keyword_suggestions(
    query: str, timeout: float = 10.0
) -> list[KeywordSuggestion]

取得關鍵字建議

Parameters:

Name	Type	Description	Default
query	str	搜尋關鍵字	required
timeout	float	請求超時時間（秒）	10.0

Returns:

Type	Description
list[KeywordSuggestion]	關鍵字建議列表

Source code in src/gurume/suggest.py

def get_keyword_suggestions(query: str, timeout: float = 10.0) -> list[KeywordSuggestion]:
    """取得關鍵字建議

    Args:
        query: 搜尋關鍵字
        timeout: 請求超時時間（秒）

    Returns:
        關鍵字建議列表
    """
    if not query or not query.strip():
        return []

    params = {"sk": query.strip()}

    try:
        resp = httpx.get(
            url=SUGGEST_URL,
            params=params,
            headers=_build_headers(),
            timeout=timeout,
            follow_redirects=True,
        )
        resp.raise_for_status()
        data = resp.json()
        if isinstance(data, dict) and data.get("suggest_empty"):
            raise TabelogSuggestUnavailableError(TabelogSuggestUnavailableError.HELP)
        if not isinstance(data, list):
            return []
    except TabelogSuggestUnavailableError:
        raise
    except (httpx.HTTPError, ValueError):
        return []
    else:
        return _parse_keyword_suggestions(data)

get_keyword_suggestions_async async

get_keyword_suggestions_async(
    query: str, request_timeout: float = 10.0
) -> list[KeywordSuggestion]

取得關鍵字建議（異步版本）

Parameters:

Name	Type	Description	Default
query	str	搜尋關鍵字	required
request_timeout	float	請求超時時間（秒）	10.0

Returns:

Type	Description
list[KeywordSuggestion]	關鍵字建議列表

Source code in src/gurume/suggest.py

async def get_keyword_suggestions_async(query: str, request_timeout: float = 10.0) -> list[KeywordSuggestion]:
    """取得關鍵字建議（異步版本）

    Args:
        query: 搜尋關鍵字
        request_timeout: 請求超時時間（秒）

    Returns:
        關鍵字建議列表
    """
    if not query or not query.strip():
        return []

    params = {"sk": query.strip()}

    try:
        async with httpx.AsyncClient(timeout=request_timeout, follow_redirects=True) as client:
            resp = await client.get(url=SUGGEST_URL, params=params, headers=_build_headers())
            resp.raise_for_status()
            data = resp.json()
            if isinstance(data, dict) and data.get("suggest_empty"):
                raise TabelogSuggestUnavailableError(TabelogSuggestUnavailableError.HELP)
            if not isinstance(data, list):
                return []
    except TabelogSuggestUnavailableError:
        raise
    except (httpx.HTTPError, ValueError):
        return []
    else:
        return _parse_keyword_suggestions(data)