suggest

gurume.suggest

Area and keyword suggestion helpers.

AreaSuggestion dataclass

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

Area suggestion.

KeywordSuggestion dataclass

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

Keyword suggestion.

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]

Get area suggestions.

Parameters:

Name	Type	Description	Default
query	str	Search keyword.	required
timeout	float	Request timeout in seconds.	10.0

Returns:

Type	Description
list[AreaSuggestion]	List of area suggestions.

Source code in src/gurume/suggest.py

def get_area_suggestions(query: str, timeout: float = 10.0) -> list[AreaSuggestion]:
    """Get area suggestions.

    Args:
        query: Search keyword.
        timeout: Request timeout in seconds.

    Returns:
        List of area suggestions.
    """
    if not query or not query.strip():
        return []

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

    try:
        resp = requests.get(
            url=SUGGEST_URL,
            params=params,
            headers=_build_headers(),
            timeout=timeout,
            allow_redirects=True,
            impersonate=DEFAULT_IMPERSONATE,
        )
        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 (request_errors.RequestException, 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]

Get area suggestions asynchronously.

Parameters:

Name	Type	Description	Default
query	str	Search keyword.	required
request_timeout	float	Request timeout in seconds.	10.0

Returns:

Type	Description
list[AreaSuggestion]	List of area suggestions.

Source code in src/gurume/suggest.py

async def get_area_suggestions_async(query: str, request_timeout: float = 10.0) -> list[AreaSuggestion]:
    """Get area suggestions asynchronously.

    Args:
        query: Search keyword.
        request_timeout: Request timeout in seconds.

    Returns:
        List of area suggestions.
    """
    if not query or not query.strip():
        return []

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

    try:
        async with requests.AsyncSession(
            timeout=request_timeout,
            allow_redirects=True,
            impersonate=DEFAULT_IMPERSONATE,
        ) 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 (request_errors.RequestException, ValueError):
        return []
    else:
        return _parse_area_suggestions(data)

get_keyword_suggestions

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

Get keyword suggestions.

Parameters:

Name	Type	Description	Default
query	str	Search keyword.	required
timeout	float	Request timeout in seconds.	10.0

Returns:

Type	Description
list[KeywordSuggestion]	List of keyword suggestions.

Source code in src/gurume/suggest.py

def get_keyword_suggestions(query: str, timeout: float = 10.0) -> list[KeywordSuggestion]:
    """Get keyword suggestions.

    Args:
        query: Search keyword.
        timeout: Request timeout in seconds.

    Returns:
        List of keyword suggestions.
    """
    if not query or not query.strip():
        return []

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

    try:
        resp = requests.get(
            url=SUGGEST_URL,
            params=params,
            headers=_build_headers(),
            timeout=timeout,
            allow_redirects=True,
            impersonate=DEFAULT_IMPERSONATE,
        )
        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 (request_errors.RequestException, 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]

Get keyword suggestions asynchronously.

Parameters:

Name	Type	Description	Default
query	str	Search keyword.	required
request_timeout	float	Request timeout in seconds.	10.0

Returns:

Type	Description
list[KeywordSuggestion]	List of keyword suggestions.

Source code in src/gurume/suggest.py

async def get_keyword_suggestions_async(query: str, request_timeout: float = 10.0) -> list[KeywordSuggestion]:
    """Get keyword suggestions asynchronously.

    Args:
        query: Search keyword.
        request_timeout: Request timeout in seconds.

    Returns:
        List of keyword suggestions.
    """
    if not query or not query.strip():
        return []

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

    try:
        async with requests.AsyncSession(
            timeout=request_timeout,
            allow_redirects=True,
            impersonate=DEFAULT_IMPERSONATE,
        ) 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 (request_errors.RequestException, ValueError):
        return []
    else:
        return _parse_keyword_suggestions(data)