jwlib.search

Wrapper for the jw.org search API.

>>> import jwlib.search as jw
>>> page = jw.search('Caleb')
>>> for r in page.results:
>>>     print(r.title, r.url_jw)

jwlib.search.search(query: str, *, filter_type='', language='E', sort='', token='') → ResultPage[source]

Perform a search and return a ResultPage.

Parameters:

query – search term
filter_type – see FILTER_* in const
language – language code
sort – see SORT_* in const
token – authentication token, acquired if empty (see ResultPage.token)

class jwlib.search.ResultPage(data: dict, token: str)[source]

Page of search results, navigation and statistics.

__init__(data: dict, token: str)[source]

classmethod from_url(url: str, token: str = '')[source]

Load a search page from a URL.

Parameters:

url – complete search query URL, like the one from PageLink.url.
token – authentication token, acquired if empty (see ResultPage.token).

property filters: List[PageLink]: List of links that will apply different search filters.

property first: PageLink | None: Link to the first page, or None if there are no results.

property insight: SearchInsight: Information about the results.

property last: PageLink | None: Link to the last page, or None if there’s just one page.

property layout: List[str]

Tags that control the webpage layout.

Known values:

flat - results are shown as rows
grid - results are shown as a grid
audio
videos
publications

property messages: List[str]: List of error messages, etc.

property next: PageLink | None: Link to the next page, or None if this is the last page.

property pagination: List[PageLink]: List of navigation links.

property pagination_label: str

Human-readable navigation info.

For example “Showing 1 - 12 of 341”.

property previous: PageLink | None: Link to the previous page, or None if this is the first page.

property results: List[Result]

List of search results.

If you’re using FILTER_ALL, this will flatten all groups into a single list of results.

property result_groups: List[ResultGroup]

List of search result groups.

When using FILTER_ALL, the search result may contain videos, music and publications. These will be grouped in separate sections on the search page, just like this function returns them.

When using any other filter, the webpage doesn’t put results in groups (since there’s only one). In that case, this property will still return a single unnamed group containing the results. To make life easier, the result property will flatten all groups into a single list of results.

property sorts: List[PageLink]: Links to pages where the results are sorted in some other order.

property token: str: JWT authentication token

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.search.ResultGroup(data: dict, parent: ResultPage)[source]

Group of Result s of similar type.

__init__(data: dict, parent: ResultPage)[source]

property label: str

Group header.

For example “Audio”, “Videos”, or an empty string (for publications).

property layout: List[str]

Tags that control the webpage layout.

Known values:

flat - results are shown as rows
carousel - results are shown horizontally
audio
videos

property links: List[PageLink]: Links found in the group header.

property results: List[Result]: List of results in the group.

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.search.Result(data: dict)[source]

Search result, including title, image and URL

property context: str: Item category, like “BOOKS”, used as a header text.

property deep_links: List[DeepLink]: List of links to specific points in time

property duration: int: Duration in seconds

property image: str | None: Image URL.

property key: str: Code name, excluding language code.

property snippet: str: Matching text, with the matching text enclosed in <strong></strong>.

property title: str: Display name.

property type: str

Item type.

See RESULT_* in const.

property urls: Dict[str, str]

Dictionary of links to this item.

Example:

{'jw.org': 'https://www.jw.org/...',
 'wol': 'https://wol.jw.org/...'}

property url_jw: str | None: URL to this item at jw.org.

property url_wol: str | None: URL to this item at wol.jw.org.

__init__(data: dict)

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.search.PageLink(data: dict, parent: ResultPage)[source]

Link to a ResultPage.

__init__(data: dict, parent: ResultPage)[source]

property label: str: Link text.

open() → ResultPage[source]: Fetch and return the ResultPage.

property selected: bool: True if the link is currently selected (used to indicate active filter, etc.).

property type: str | None

Optional link type.

Known values:

first - first page
next - next page
last - last page
more - more items of this type (video, audio, etc.)

property url: str: Link destination, use PageLink.open() to open it.

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.search.DeepLink(data: dict)[source]

Link to a specific part of a video

property key: int: Media code name, similar to Result.key.

property label: str: Label like “Jump to 3:00”.

property rank: int: Use-case unknown.

property snippet: str: Blurb, similar to Result.snippet

property title: str: Use-case unknown.

property urls: Dict[str, str]: Dictionary of links, similar to Result.urls.

property url_jw: str | None: URL to this item at jw.org.

__init__(data: dict)

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.search.SearchInsight(data: dict)[source]

Information about a search.

property filter: str

Current search filter.

See FILTER_* in const for valid values.

property offset: int: Number of items skipped before the first item on this page (used for pagination).

property page: int: Page number, starting from 1.

property query: str: The search term.

property sort: str

Current sort method.

See SORT_* in const for valid values.

property total: int: Total number of items found (on all pages).

property total_relation: str

Precision of the total value.

Known values:

eq - there are exactly ‘total’ items
gte - there are more than ‘total’ items

__init__(data: dict)

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.