wikipediaapi

Wikipedia-API is easy to use wrapper for extracting information from Wikipedia.

It supports extracting texts, sections, links, categories, translations, etc. from Wikipedia. Documentation provides code snippets for the most common use cases.

class wikipediaapi.WikipediaImage(wiki: object, title: str, ns: Namespace | int = 6, language: str = 'en', variant: str | None = None, url: str | None = None)

Lazy representation of a Wikipedia/Commons file page. A WikipediaImage is created by internal resource methods when building image lists. It requires no network call at construction time; accessing imageinfo (or any convenience property derived from it) triggers the minimum API call needed to populate the cache. Named properties (always available without a network call): :attr language: two-letter language code this image belongs to :attr variant: language variant used for auto-conversion, or None :attr title: file title including the File: prefix :attr ns: integer namespace number (6 for files) Dynamically fetched (trigger an imageinfo call on first access): * imageinfo — list of ImageInfo objects * url, descriptionurl, descriptionshorturl — URLs * width, height, size — dimensions and file size * mime, mediatype, sha1, timestamp, user

property sections: list[WikipediaPageSection]

File pages have no sections; always returns an empty list.

sections_by_title(title: str) → list[WikipediaPageSection]

File pages have no sections; always returns an empty list.

exists() → bool

Return True if this file exists (local or on Commons). A file is considered to exist when it has a positive pageid or when the API returned a known="" key (indicating the file is hosted on Wikimedia Commons). Triggers an imageinfo fetch on first call if the cache has not yet been populated. :return: True if the file is available, False otherwise

property pageid: int

MediaWiki numeric page ID (positive for existing images, negative for missing).

Returns a deterministic page ID based on image title hash when image exists either locally (pageid > 0) or on Wikimedia Commons (known attribute present). Returns a negative value when image does not exist. Triggers an imageinfo fetch on first access if the cache has not yet been populated.

Returns:

positive integer if image exists, negative integer otherwise

property imageinfo: list[ImageInfo]

List of ImageInfo objects for this file. Triggers an imageinfo API call on first access using default parameters. Subsequent accesses return the cached value. Returns:

List of ImageInfo objects; empty list if the file does not exist or has no metadata.

property url: str | None

Full URL of the file, or None if unavailable.

property descriptionurl: str | None

URL of the file description page, or None if unavailable.

property descriptionshorturl: str | None

Short URL of the file description page, or None if unavailable.

property width: int | None

Image width in pixels, or None if unavailable.

property height: int | None

Image height in pixels, or None if unavailable.

property size: int | None

File size in bytes, or None if unavailable.

property mime: str | None

MIME type of the file (e.g. "image/jpeg"), or None.

property mediatype: str | None

MediaWiki media type (e.g. "BITMAP"), or None.

property sha1: str | None

SHA-1 hash of the file content, or None if unavailable.

property timestamp: str | None

ISO 8601 timestamp of this file revision, or None.

property user: str | None

Username of the uploader, or None if unavailable.

class wikipediaapi.AsyncWikipediaImage(wiki: object, title: str, ns: Namespace | int = 6, language: str = 'en', variant: str | None = None, url: str | None = None)

Lazy async representation of a Wikipedia/Commons file page.

Mirrors WikipediaImage but exposes all data-fetching as awaitables instead of blocking properties. A file stub is created by internal resource methods with no network call; each awaitable property fetches its data on the first await.

Named properties (always available without a network call):

Attr language:

two-letter language code this image belongs to

Attr variant:

language variant used for auto-conversion, or None

Attr title:

file title including the File: prefix

Attr ns:

integer namespace number (6 for files)

Awaitable data properties (trigger an imageinfo call on first await):

  • await image.imageinfo — list of ImageInfo

  • await image.url, await image.descriptionurl, etc.

property sections: list[WikipediaPageSection]

File pages have no sections; always returns an empty list.

sections_by_title(title: str) → list[WikipediaPageSection]

File pages have no sections; always returns an empty list.

async exists() → bool

Return True if this file exists (local or on Commons).

Triggers an imageinfo fetch on first call if the cache has not yet been populated.

Returns:

True if the file is available, False otherwise

property pageid: Coroutine[Any, Any, int]

Awaitable: MediaWiki numeric page ID (positive for existing, negative for missing).

Returns a deterministic page ID based on image title hash when image exists either locally (pageid > 0) or on Wikimedia Commons (known attribute present). Returns a negative value when image does not exist. Triggers an imageinfo fetch on first access if the cache has not yet been populated.

Returns:

coroutine resolving to positive integer if image exists, negative integer otherwise

property imageinfo: Coroutine[Any, Any, list[ImageInfo]]

Awaitable: list of ImageInfo objects.

Triggers an imageinfo API call on first access using default parameters. Subsequent accesses return the cached value.

Returns:

Coroutine resolving to a list of ImageInfo objects.

property url: Coroutine[Any, Any, str | None]

Awaitable: full URL of the file, or None if unavailable.

property descriptionurl: Coroutine[Any, Any, str | None]

Awaitable: URL of the file description page, or None.

property descriptionshorturl: Coroutine[Any, Any, str | None]

Awaitable: short URL of the file description page, or None.

property width: Coroutine[Any, Any, int | None]

Awaitable: image width in pixels, or None.

property height: Coroutine[Any, Any, int | None]

Awaitable: image height in pixels, or None.

property size: Coroutine[Any, Any, int | None]

Awaitable: file size in bytes, or None.

property mime: Coroutine[Any, Any, str | None]

Awaitable: MIME type of the file, or None.

property mediatype: Coroutine[Any, Any, str | None]

Awaitable: MediaWiki media type, or None.

property sha1: Coroutine[Any, Any, str | None]

Awaitable: SHA-1 hash of the file content, or None.

property timestamp: Coroutine[Any, Any, str | None]

Awaitable: ISO 8601 timestamp of this file revision, or None.

property user: Coroutine[Any, Any, str | None]

Awaitable: username of the uploader, or None.

class wikipediaapi.Coordinate(lat: float, lon: float, primary: bool, globe: str = 'earth', type: str | None = None, name: str | None = None, dim: int | None = None, country: str | None = None, region: str | None = None, dist: float | None = None)

A single geographic coordinate associated with a Wikipedia page.

Represents one entry from prop=coordinates API response. Always contains lat, lon, and primary; additional fields are populated when requested via prop parameter.

Args:

lat: Latitude in decimal degrees. lon: Longitude in decimal degrees. primary: True if this is primary coordinate for page. globe: Celestial body coordinates refer to. type: Type of geographic object (e.g. "city"). name: Name of geographic object. dim: Approximate size of object in meters. country: ISO 3166-1 alpha-2 country code. region: ISO 3166-2 region code (part after dash). dist: Distance in meters from a reference point, set only when

distance_from_point or distance_from_page is used.

class wikipediaapi.GeoBox(top_left: GeoPoint = GeoPoint(lat=0.0, lon=0.0), bottom_right: GeoPoint = GeoPoint(lat=0.0, lon=0.0))

A geographic bounding box defined by two validated corner points.

Represents MediaWiki’s gsbbox value in a pythonic structured way.

Args:

top_left: Top-left corner of box. bottom_right: Bottom-right corner of box.

Raises:

ValueError: If top-left latitude is smaller than bottom-right latitude. ValueError: If top-left longitude is greater than bottom-right longitude.

to_mediawiki() → str

Convert this box to MediaWiki "top|left|bottom|right" format.

Returns:

The "top_lat|left_lon|bottom_lat|right_lon" string expected by MediaWiki query params.

class wikipediaapi.GeoPoint(lat: float = 0.0, lon: float = 0.0)

A geographic point with latitude/longitude validation.

Used as pythonic input for API parameters that previously required MediaWiki’s "lat|lon" string format.

Args:

lat: Latitude in decimal degrees, valid range [-90.0, 90.0]. lon: Longitude in decimal degrees, valid range [-180.0, 180.0].

Raises:

ValueError: If lat is outside [-90.0, 90.0]. ValueError: If lon is outside [-180.0, 180.0].

to_mediawiki() → str

Convert this point to MediaWiki "lat|lon" format.

Returns:

The "lat|lon" string expected by MediaWiki query params.

class wikipediaapi.GeoSearchMeta(dist: float, lat: float, lon: float, primary: bool)

Contextual metadata attached to pages returned by a geosearch query.

Accessible via page.geosearch_meta on pages produced by wiki.geosearch(). Contains distance from search centre and coordinate that was matched.

Args:

dist: Distance in meters from search centre. lat: Latitude of matched coordinate. lon: Longitude of matched coordinate. primary: True if matched coordinate is the primary one.

class wikipediaapi.ImageInfo(timestamp: str | None = None, user: str | None = None, url: str | None = None, descriptionurl: str | None = None, descriptionshorturl: str | None = None, width: int | None = None, height: int | None = None, size: int | None = None, mime: str | None = None, mediatype: str | None = None, sha1: str | None = None)

Metadata for one revision of a file from prop=imageinfo.

Represents one entry in the imageinfo list returned by the MediaWiki prop=imageinfo API. All fields are optional because the API may omit them depending on the iiprop parameter and file availability.

Args:

timestamp: ISO 8601 timestamp of this file revision. user: Username of the uploader. url: Full URL of the file. descriptionurl: URL of the file description page. descriptionshorturl: Short URL of the file description page. width: Image width in pixels. height: Image height in pixels. size: File size in bytes. mime: MIME type of the file (e.g. "image/jpeg"). mediatype: MediaWiki media type (e.g. "BITMAP"). sha1: SHA-1 hash of the file content.

class wikipediaapi.SearchMeta(snippet: str = '', size: int = 0, wordcount: int = 0, timestamp: str = '')

Contextual metadata attached to pages returned by a search query.

Accessible via page.search_meta on pages produced by wiki.search(). Contains search-specific fields like highlighted snippet.

Args:

snippet: HTML snippet with query-term highlighting. size: Page size in bytes. wordcount: Word count of page. timestamp: ISO 8601 timestamp of last edit.

class wikipediaapi.SearchResults(pages: PagesDict, totalhits: int = 0, suggestion: str | None = None)

Wrapper for search results combining pages with aggregate metadata.

Returned by wiki.search(). The pages attribute is a PagesDict keyed by title; each page carries a SearchMeta sub-object accessible via page.search_meta.

Args:

pages: Dictionary of matching pages keyed by title. totalhits: Total number of matches reported by the API. suggestion: Spelling suggestion from search backend, or None.

class wikipediaapi.PagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Dictionary of WikipediaPage objects with batch methods.

Inherits from dict[str, WikipediaPage] and adds a reference to wiki client so that batch operations can be dispatched in a single API call per chunk of 50 pages.

Args:

wiki: The Wikipedia client instance. data: Optional initial mapping of {title: WikipediaPage}.

coordinates(*, limit: int = 10, primary: WikiCoordinateType = CoordinateType.PRIMARY, prop: Iterable[WikiCoordinatesProp] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: WikipediaPage | None = None) → dict[WikipediaPage, list[Coordinate]]

Batch-fetch coordinates for all pages in this dict.

Delegates to wiki.batch_coordinates() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum coordinates per page (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

{page: [Coordinate, ...]} for every page in this dict.

images(*, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, PagesDict]

Batch-fetch images for all pages in this dict.

Delegates to wiki.batch_images() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum images per page (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

{title: PagesDict} for every page in this dict.

class wikipediaapi.AsyncPagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Async dictionary of AsyncWikipediaPage objects with batch methods.

Async mirror of PagesDict. Batch methods are coroutines.

Args:

wiki: The AsyncWikipedia client instance. data: Optional initial mapping of {title: AsyncWikipediaPage}.

async coordinates(*, limit: int = 10, primary: WikiCoordinateType = CoordinateType.PRIMARY, prop: Iterable[WikiCoordinatesProp] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: AsyncWikipediaPage | None = None) → dict[AsyncWikipediaPage, list[Coordinate]]

Async batch-fetch coordinates for all pages in this dict.

Delegates to wiki.batch_coordinates() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum coordinates per page (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

{page: [Coordinate, ...]} for every page in this dict.

async images(*, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, PagesDict]

Async batch-fetch images for all pages in this dict.

Delegates to wiki.batch_images() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum images per page (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

{title: PagesDict} for every page in this dict.

class wikipediaapi.ImagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Dictionary of WikipediaImage objects with batch methods.

Inherits from dict[str, WikipediaImage] and adds a reference to the wiki client so that batch operations can be dispatched in a single API call per chunk of 50 images.

Args:

wiki: The Wikipedia client instance. data: Optional initial mapping of {title: WikipediaImage}.

imageinfo(*, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → dict[str, list[ImageInfo]]

Batch-fetch imageinfo for all images in this dict.

Delegates to wiki.batch_imageinfo() which sends multi-title API requests (up to 50 titles per request).

Args:
prop: Tuple of iiprop field names controlling which fields

are returned.

limit: Maximum number of file revisions to return (1–500).

Returns:

{title: [ImageInfo, ...]} for every image in this dict.

class wikipediaapi.AsyncImagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Async dictionary of AsyncWikipediaImage objects.

Async mirror of ImagesDict. Batch methods are coroutines.

Args:

wiki: The AsyncWikipedia client instance. data: Optional initial mapping of {title: AsyncWikipediaImage}.

async imageinfo(*, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → dict[str, list[ImageInfo]]

Async batch-fetch imageinfo for all images in this dict.

Delegates to wiki.batch_imageinfo() which sends multi-title API requests (up to 50 titles per request).

Args:
prop: Tuple of iiprop field names controlling which fields

are returned.

limit: Maximum number of file revisions to return (1–500).

Returns:

{title: [ImageInfo, ...]} for every image in this dict.

class wikipediaapi.BaseHTTPClient(user_agent: str, language: str = 'en', variant: str | None = None, extract_format: ExtractFormat = ExtractFormat.WIKI, headers: dict[str, Any] | None = None, extra_api_params: dict[str, Any] | None = None, max_retries: int = 3, retry_wait: float = 1.0, **kwargs: Any)

Abstract base for synchronous and asynchronous HTTP clients.

Provides shared constructor logic (parameter validation, header construction, configuration storage) and stateless helpers used by both SyncHTTPClient and AsyncHTTPClient.

Subclasses must implement _get(language, params) (sync or async) that issues the actual HTTP request.

Note on HTTP Library: This implementation uses httpx as the underlying HTTP client library. Advanced HTTP configuration (timeouts, proxies, SSL settings, connection limits, etc.) is exposed through the SyncHTTPClient and AsyncHTTPClient classes. For most use cases, use the standard Wikipedia API parameters. Direct httpx configuration should only be needed for advanced use cases.

Instance attributes set by __init__():

Attr language:

normalised Wikipedia language code (e.g. "en")

Attr variant:

normalised language variant, or None

Attr extract_format:

ExtractFormat used for text extraction

class wikipediaapi.SyncHTTPClient(*args: Any, **kwargs: Any)

Blocking HTTP client built on httpx.Client.

Creates a persistent httpx.Client at construction time and uses it for all requests. Retry logic is implemented via tenacity.Retrying with _RetryAfterWait as wait strategy and _is_retryable() as retry predicate.

Attr _client:

underlying httpx.Client instance

class wikipediaapi.AsyncHTTPClient(*args: Any, **kwargs: Any)

Non-blocking HTTP client built on httpx.AsyncClient.

Creates a persistent httpx.AsyncClient at construction time and uses it for all requests. Retry logic is implemented via tenacity.AsyncRetrying with _RetryAfterWait as wait strategy and _is_retryable() as retry predicate.

All request methods are coroutines and must be await-ed.

Attr _client:

underlying httpx.AsyncClient instance

class wikipediaapi.BaseWikipediaResource

Mixin providing shared Wikipedia API logic for both sync and async subclasses.

This class contains all parameter builders, response parsers, and dispatch helpers. It has no HTTP transport of its own; subclasses must supply a _get(language, params) method (sync or async) and instance attributes extract_format and _extra_api_params.

Subclassing convention:

class wikipediaapi.WikipediaResource

Synchronous mixin providing the public Wikipedia API surface.

Combines BaseWikipediaResource (parsing & dispatch logic) with SyncHTTPClient (blocking HTTP via httpx) to form a concrete synchronous client. Intended to be used via multiple inheritance:

class Wikipedia(WikipediaResource, SyncHTTPClient): ...

All API methods block until HTTP response is received and parsed.

page(title: str, ns: Namespace | int = Namespace.MAIN, unquote: bool = False) → WikipediaPage

Return a WikipediaPage for the given title (lazy, no network call).

Creates a stub page bound to this Wikipedia instance. No HTTP request is made at construction time; individual properties (text, summary, links, …) fetch their data on first access.

Parameters:

  • title – page title as it appears in Wikipedia URLs; spaces may be replaced by underscores (e.g. "Python_(programming_language)")

  • ns – namespace; defaults to Namespace.MAIN

  • unquote – if True, percent-decode title before use

Returns:

WikipediaPage bound to this instance

article(title: str, ns: Namespace | int = Namespace.MAIN, unquote: bool = False) → WikipediaPage

Alias for page().

Provided for semantic clarity when the caller knows the target is a main-namespace article rather than, e.g., a category or file page.

Parameters:

  • title – page title as used in Wikipedia URLs

  • ns – namespace; defaults to Namespace.MAIN

  • unquote – if True, percent-decode title before use

Returns:

WikipediaPage bound to this instance

extracts(page: WikipediaPage, **kwargs: Any) → str

Fetch and return the plain-text or HTML extract for a page.

Output format (plain-text wiki markup vs. HTML) is controlled by the extract_format argument passed to the Wikipedia constructor. Pass additional extracts API parameters via kwargs to narrow the result (e.g. exsentences=2, exintro=True).

API reference:

Example:

import wikipediaapi
wiki = wikipediaapi.Wikipedia('MyBot/1.0', 'en')
page = wiki.page('Python_(programming_language)')
print(wiki.extracts(page, exsentences=1))
Parameters:

  • page – page whose extract to fetch

  • kwargs – extra extracts API parameters forwarded verbatim

Returns:

introductory summary string

Raises:
info(page: WikipediaPage) → WikipediaPage

Fetch general page metadata and populate the page object in-place.

Calls the info prop and copies all returned fields (protection level, talk page ID, watcher counts, canonical URL, display title, variant titles, …) into page._attributes. Returns page itself so callers can chain calls.

API reference:

Parameters:

page – page to fetch metadata for

Returns:

page populated with info fields; page unchanged if the page does not exist (pageid is set to a negative value)

Raises:

Fetch inter-language links and return them keyed by language code.

Each value is a stub WikipediaPage with its language attribute set and canonical URL pre-populated. Up to 500 language links are returned in a single request.

API reference:

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. lllang="de" to filter to a single target language)

Returns:

{language_code: WikipediaPage}; {} if the page is missing

Raises:

Fetch all outgoing wiki-links and return them keyed by title.

Follows API pagination automatically (plcontinue cursor) so the returned dict always contains the complete set of links regardless of how many round-trips were required. Each value is a stub WikipediaPage for lazy expansion.

API reference:

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. plnamespace=0)

Returns:

{title: WikipediaPage}; {} if the page is missing

Raises:

Fetch all pages that link to the page and return them keyed by title.

Follows API pagination automatically (blcontinue cursor) so the returned dict is always complete. Each value is a stub WikipediaPage.

API reference:

Parameters:

  • page – target page (backlinks point to this page)

  • kwargs – extra API parameters (e.g. blnamespace=0, blfilterredir="nonredirects")

Returns:

{title: WikipediaPage} for all pages linking here

Raises:
categories(page: WikipediaPage, **kwargs: Any) → PagesDict

Fetch all categories this page belongs to, keyed by category title.

Each value is a stub WikipediaPage in the Category: namespace.

API reference:

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. clshow="!hidden" to exclude hidden categories)

Returns:

{title: WikipediaPage}; {} if the page is missing

Raises:
categorymembers(page: WikipediaPage, **kwargs: Any) → PagesDict

Fetch all members of a category page and return them keyed by title.

Follows API pagination automatically (cmcontinue cursor). page must be in the Category: namespace. Each value is a stub WikipediaPage with pageid pre-set.

API reference:

Parameters:

  • page – category page (must have ns == Namespace.CATEGORY)

  • kwargs – extra API parameters (e.g. cmtype="subcat" to list only sub-categories)

Returns:

{title: WikipediaPage} for all category members

Raises:
coordinates(page: WikipediaPage, *, limit: int = 10, primary: CoordinateType | str = CoordinateType.PRIMARY, prop: Iterable[CoordinatesProp | str] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: WikipediaPage | None = None) → list[Coordinate]

Fetch geographic coordinates for a page.

Calls prop=coordinates with the given parameters and caches result per parameter set. page.coordinates (the property) calls this with defaults.

API reference:

Args:

page: Page to fetch coordinates for. limit: Maximum coordinates to return (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

List of Coordinate objects; empty list if the page is missing.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

batch_coordinates(pages: list[WikipediaPage], *, limit: int = 10, primary: CoordinateType | str = CoordinateType.PRIMARY, prop: Iterable[CoordinatesProp | str] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: WikipediaPage | None = None) → dict[WikipediaPage, list[Coordinate]]

Batch-fetch coordinates for multiple pages.

Sends multi-title API requests (up to 50 titles per request) and distributes results to each page’s cache.

Args:

pages: List of pages to fetch coordinates for. limit: Maximum coordinates per page (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

{page: [Coordinate, ...]} for every page.

images(page: WikipediaPage, *, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → ImagesDict

Fetch images (files) used on a page.

Calls prop=images with automatic pagination and caches result per parameter set.

API reference:

Args:

page: Page to fetch images for. limit: Maximum images to return (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

ImagesDict keyed by image title; empty if the page is missing.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

batch_images(pages: list[WikipediaPage], *, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, ImagesDict]

Batch-fetch images for multiple pages.

Sends multi-title API requests (up to 50 titles per request) and distributes results to each page’s cache.

Args:

pages: List of pages to fetch images for. limit: Maximum images per page (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

{title: ImagesDict} for every page.

imageinfo(image: WikipediaImage, *, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → list[ImageInfo]

Fetch metadata for a single file page.

Calls prop=imageinfo and caches the result per parameter set.

API reference:

Args:

image: File page to fetch metadata for. prop: Tuple of iiprop field names. limit: Maximum number of file revisions to return (1–500).

Returns:

List of ImageInfo objects; empty list if the file does not exist.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

batch_imageinfo(images: list[WikipediaImage], *, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → dict[str, list[ImageInfo]]

Batch-fetch imageinfo for multiple file pages.

Sends multi-title API requests (up to 50 titles per request) and distributes results to each image’s cache.

Args:

images: List of file pages to fetch metadata for. prop: Tuple of iiprop field names. limit: Maximum number of file revisions to return (1–500).

Returns:

{title: [ImageInfo, ...]} for every image.

geosearch(*, coord: GeoPoint | None = None, page: WikipediaPage | None = None, bbox: GeoBox | None = None, radius: int = 500, max_dim: int | None = None, sort: GeoSearchSort | str = GeoSearchSort.DISTANCE, limit: int = 10, globe: Globe | str = Globe.EARTH, ns: Namespace | int = Namespace.MAIN, prop: Iterable[CoordinatesProp | str] | None = None, primary: CoordinateType | str | None = None) → PagesDict

Search for pages with coordinates near a location.

Calls list=geosearch and returns WikipediaPage stubs with pre-cached coordinates and GeoSearchMeta sub-objects.

At least one of coord, page, or bbox must be provided.

API reference:

Args:

coord: Centre point as GeoPoint. page: Title of page whose coordinates to use as centre. bbox: Bounding box as GeoBox. radius: Search radius in meters (10–10000). max_dim: Exclude objects larger than this many meters. sort: Sort order: "distance" or "relevance". limit: Maximum pages to return (1–500). globe: Celestial body. ns: Restrict to this namespace number. prop: Additional properties as an iterable. primary: Which coordinates to consider.

Returns:

PagesDict keyed by page title.

random(*, ns: Namespace | int = Namespace.MAIN, filter_redirect: RedirectFilter | str = RedirectFilter.NONREDIRECTS, min_size: int | None = None, max_size: int | None = None, limit: int = 1) → PagesDict

Fetch a set of random pages.

Calls list=random and returns WikipediaPage stubs with pageid pre-set.

API reference:

Args:

ns: Restrict to this namespace number. filter_redirect: Redirect filter: "all", "nonredirects",

or "redirects".

min_size: Minimum page size in bytes. max_size: Maximum page size in bytes. limit: Number of random pages to return (1–500).

Returns:

PagesDict keyed by page title.

search(query: str, *, ns: Namespace | int = Namespace.MAIN, limit: int = 10, prop: Iterable[SearchProp | str] | None = None, info: Iterable[SearchInfo | str] | None = None, sort: SearchSort | str = SearchSort.RELEVANCE, what: SearchWhat | str | None = None, interwiki: bool = False, enable_rewrites: bool = False, qi_profile: SearchQiProfile | str | None = None) → SearchResults

Perform a full-text search.

Calls list=search and returns a SearchResults wrapper containing WikipediaPage stubs with SearchMeta sub-objects, plus aggregate metadata.

API reference:

Args:

query: Search string (required). ns: Namespace to search in. limit: Maximum results to return (1–500). prop: Properties as an iterable (deprecated upstream). info: Metadata as an iterable. sort: Sort order. what: Search type: "title", "text", or "nearmatch". interwiki: Include interwiki results. enable_rewrites: Allow the backend to rewrite the query. qi_profile: Query-independent ranking profile.

Returns:

SearchResults with pages, totalhits, and suggestion.

pages(titles: list[str], ns: Namespace | int = Namespace.MAIN) → PagesDict

Create a PagesDict of lazy page stubs.

No network call is made; each page fetches data on demand.

Args:

titles: List of page titles. ns: Namespace for all pages; defaults to Namespace.MAIN.

Returns:

PagesDict keyed by title.

class wikipediaapi.AsyncWikipediaResource

Asynchronous mixin providing the public Wikipedia API surface.

Combines BaseWikipediaResource (parsing & dispatch logic) with AsyncHTTPClient (non-blocking HTTP via httpx) to form a concrete async client. Intended to be used via multiple inheritance:

class AsyncWikipedia(AsyncWikipediaResource, AsyncHTTPClient): ...

All API methods are coroutines and must be awaited. Pages are represented by AsyncWikipediaPage objects whose properties are also coroutines.

page(title: str, ns: Namespace | int = Namespace.MAIN, unquote: bool = False) → AsyncWikipediaPage

Return an AsyncWikipediaPage for the given title (lazy, no network call).

Creates a stub async page bound to this Wikipedia instance. No HTTP request is made at construction time; each property coroutine fetches its data on first await.

Parameters:

  • title – page title as it appears in Wikipedia URLs

  • ns – namespace; defaults to Namespace.MAIN

  • unquote – if True, percent-decode title before use

Returns:

AsyncWikipediaPage bound to this instance

article(title: str, ns: Namespace | int = Namespace.MAIN, unquote: bool = False) → AsyncWikipediaPage

Alias for page().

Provided for semantic clarity when the caller knows the target is a main-namespace article rather than, e.g., a category or file page.

Parameters:

  • title – page title as used in Wikipedia URLs

  • ns – namespace; defaults to Namespace.MAIN

  • unquote – if True, percent-decode title before use

Returns:

AsyncWikipediaPage bound to this instance

async extracts(page: AsyncWikipediaPage, **kwargs: Any) → str

Async version of WikipediaResource.extracts().

Fetches and returns the plain-text or HTML extract for a page. See WikipediaResource.extracts() for full documentation.

Parameters:

  • page – page whose extract to fetch

  • kwargs – extra extracts API parameters forwarded verbatim

Returns:

introductory summary string

Raises:
async info(page: AsyncWikipediaPage) → AsyncWikipediaPage

Async version of WikipediaResource.info().

Fetches general page metadata and populates the page object in-place. See WikipediaResource.info() for full documentation.

Parameters:

page – page to fetch metadata for

Returns:

page populated with info fields; page unchanged if the page does not exist

Raises:

Async version of WikipediaResource.langlinks().

Fetches inter-language links keyed by language code. See WikipediaResource.langlinks() for full documentation.

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. lllang="de")

Returns:

{language_code: AsyncWikipediaPage}; {} if missing

Raises:

Async version of WikipediaResource.links().

Fetches all outgoing wiki-links with automatic pagination. See WikipediaResource.links() for full documentation.

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. plnamespace=0)

Returns:

{title: AsyncWikipediaPage}; {} if the page is missing

Raises:

Async version of WikipediaResource.backlinks().

Fetches all pages linking to the page with automatic pagination. See WikipediaResource.backlinks() for full documentation.

Parameters:

  • page – target page (backlinks point to this page)

  • kwargs – extra API parameters (e.g. blnamespace=0)

Returns:

{title: AsyncWikipediaPage} for all linking pages

Raises:
async categories(page: AsyncWikipediaPage, **kwargs: Any) → AsyncPagesDict

Async version of WikipediaResource.categories().

Fetches all categories this page belongs to, keyed by title. See WikipediaResource.categories() for full documentation.

Parameters:

  • page – source page

  • kwargs – extra API parameters (e.g. clshow="!hidden")

Returns:

{title: AsyncWikipediaPage}; {} if the page is missing

Raises:
async categorymembers(page: AsyncWikipediaPage, **kwargs: Any) → AsyncPagesDict

Async version of WikipediaResource.categorymembers().

Fetches all members of a category page with automatic pagination. See WikipediaResource.categorymembers() for full documentation.

Parameters:

  • page – category page (must be in the Category: namespace)

  • kwargs – extra API parameters (e.g. cmtype="subcat")

Returns:

{title: AsyncWikipediaPage} for all members

Raises:
async coordinates(page: AsyncWikipediaPage, *, limit: int = 10, primary: CoordinateType | str = CoordinateType.PRIMARY, prop: Iterable[CoordinatesProp | str] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: AsyncWikipediaPage | None = None) → list[Coordinate]

Async version of WikipediaResource.coordinates().

See WikipediaResource.coordinates() for full documentation.

Parameters:

  • page – Page to fetch coordinates for.

  • limit – Maximum coordinates to return (1–500).

  • primary – Which coordinates: "primary", "secondary", "all".

  • prop – Additional properties as an iterable.

  • distance_from_point – Reference point as GeoPoint.

  • distance_from_page – Reference page.

Returns:

List of Coordinate objects; empty list if the page is missing.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

async batch_coordinates(pages: list[AsyncWikipediaPage], *, limit: int = 10, primary: CoordinateType | str = CoordinateType.PRIMARY, prop: Iterable[CoordinatesProp | str] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: AsyncWikipediaPage | None = None) → dict[AsyncWikipediaPage, list[Coordinate]]

Async version of WikipediaResource.batch_coordinates().

See WikipediaResource.batch_coordinates() for full documentation.

Parameters:

  • pages – List of pages to fetch coordinates for.

  • limit – Maximum coordinates per page (1–500).

  • primary – Which coordinates: "primary", "secondary", "all".

  • prop – Additional properties as an iterable.

  • distance_from_point – Reference point as GeoPoint.

  • distance_from_page – Reference page.

Returns:

{page: [Coordinate, ...]} for every page.

async images(page: AsyncWikipediaPage, *, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → AsyncImagesDict

Async version of WikipediaResource.images().

See WikipediaResource.images() for full documentation.

Parameters:

  • page – Page to fetch images for.

  • limit – Maximum images to return (1–500).

  • images – Specific images as an iterable.

  • direction – Sort direction as WikiDirection.

Returns:

AsyncImagesDict keyed by image title; empty if the page is missing.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

async batch_images(pages: list[AsyncWikipediaPage], *, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, AsyncImagesDict]

Async version of WikipediaResource.batch_images().

See WikipediaResource.batch_images() for full documentation.

Parameters:

  • pages – List of pages to fetch images for.

  • limit – Maximum images per page (1–500).

  • images – Specific images as an iterable.

  • direction – Sort direction as WikiDirection.

Returns:

{title: AsyncImagesDict} for every page.

async imageinfo(image: AsyncWikipediaImage, *, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → list[ImageInfo]

Async version of WikipediaResource.imageinfo().

See WikipediaResource.imageinfo() for full documentation.

Parameters:

  • image – File page to fetch metadata for.

  • prop – Tuple of iiprop field names.

  • limit – Maximum number of file revisions to return (1–500).

Returns:

List of ImageInfo objects; empty list if the file does not exist.

Raises:

WikiHttpTimeoutError: If the request times out. WikiConnectionError: If a connection cannot be established. WikiRateLimitError: If the API returns HTTP 429. WikiHttpError: If the API returns a non-success HTTP status. WikiInvalidJsonError: If the response is not valid JSON.

async batch_imageinfo(images: list[AsyncWikipediaImage], *, prop: tuple[str, ...] = ('url', 'size', 'mime', 'mediatype', 'sha1', 'timestamp', 'user'), limit: int = 1) → dict[str, list[ImageInfo]]

Async version of WikipediaResource.batch_imageinfo().

See WikipediaResource.batch_imageinfo() for full documentation.

Parameters:

  • images – List of file pages to fetch metadata for.

  • prop – Tuple of iiprop field names.

  • limit – Maximum number of file revisions to return (1–500).

Returns:

{title: [ImageInfo, ...]} for every image.

async geosearch(*, coord: GeoPoint | None = None, page: AsyncWikipediaPage | None = None, bbox: GeoBox | None = None, radius: int = 500, max_dim: int | None = None, sort: GeoSearchSort | str = GeoSearchSort.DISTANCE, limit: int = 10, globe: Globe | str = Globe.EARTH, ns: Namespace | int = Namespace.MAIN, prop: Iterable[CoordinatesProp | str] | None = None, primary: CoordinateType | str | None = None) → AsyncPagesDict

Async version of WikipediaResource.geosearch().

See WikipediaResource.geosearch() for full documentation.

Parameters:

  • coord – Centre point as GeoPoint.

  • page – Title of page whose coordinates to use as centre.

  • bbox – Bounding box as GeoBox.

  • radius – Search radius in meters (10–10000).

  • max_dim – Exclude objects larger than this many meters.

  • sort – Sort order: "distance" or "relevance".

  • limit – Maximum pages to return (1–500).

  • globe – Celestial body.

  • ns – Restrict to this namespace number.

  • prop – Additional properties as an iterable.

  • primary – Which coordinates to consider.

Returns:

AsyncPagesDict keyed by page title.

async random(*, ns: Namespace | int = Namespace.MAIN, filter_redirect: RedirectFilter | str = RedirectFilter.NONREDIRECTS, min_size: int | None = None, max_size: int | None = None, limit: int = 1) → AsyncPagesDict

Async version of WikipediaResource.random().

See WikipediaResource.random() for full documentation.

Parameters:

  • ns – Restrict to this namespace number.

  • filter_redirect – Redirect filter.

  • min_size – Minimum page size in bytes.

  • max_size – Maximum page size in bytes.

  • limit – Number of random pages to return (1–500).

Returns:

AsyncPagesDict keyed by page title.

async search(query: str, *, ns: Namespace | int = Namespace.MAIN, limit: int = 10, prop: Iterable[SearchProp | str] | None = None, info: Iterable[SearchInfo | str] | None = None, sort: SearchSort | str = SearchSort.RELEVANCE, what: SearchWhat | str | None = None, interwiki: bool = False, enable_rewrites: bool = False, qi_profile: SearchQiProfile | str | None = None) → SearchResults

Async version of WikipediaResource.search().

See WikipediaResource.search() for full documentation.

Parameters:

  • query – Search string (required).

  • ns – Namespace to search in.

  • limit – Maximum results to return (1–500).

  • prop – Properties as an iterable (deprecated upstream).

  • info – Metadata as an iterable.

  • sort – Sort order.

  • what – Search type.

  • interwiki – Include interwiki results.

  • enable_rewrites – Allow the backend to rewrite the query.

  • qi_profile – Query-independent ranking profile.

Returns:

SearchResults with pages, totalhits, and suggestion.

async pages(titles: list[str], ns: Namespace | int = Namespace.MAIN) → AsyncPagesDict

Create an AsyncPagesDict of lazy page stubs.

No network call is made; each page fetches data on demand.

Parameters:

  • titles – List of page titles.

  • ns – Namespace for all pages; defaults to Namespace.MAIN.

Returns:

AsyncPagesDict keyed by title.

class wikipediaapi.Direction(*values)

Sort direction values for image query methods.

This enum is used by images and batch_images methods in both sync and async APIs.

wikipediaapi.direction2str(direction: Direction | str) → str

Convert a WikiDirection value to a plain str.

If direction is a Direction enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

direction – direction to convert

Returns:

string representation of the direction

Examples:

from wikipediaapi import direction2str, Direction

# Convert enum to string
assert direction2str(Direction.ASCENDING) == "ascending"

# String pass-through (unchanged)
assert direction2str("ascending") == "ascending"

# Custom values pass through
assert direction2str("custom") == "custom"
class wikipediaapi.CoordinateType(*values)

Coordinate types for coordinates and geosearch methods.

This enum is used by coordinates and geosearch methods in both sync and async APIs to specify which type of coordinates to return.

ALL = 'all'

Return both primary and secondary coordinates.

PRIMARY = 'primary'

Return only primary coordinates (location of article subject).

SECONDARY = 'secondary'

Return only secondary coordinates (locations of objects mentioned in article).

wikipediaapi.coordinate_type2str(ctype: CoordinateType | str) → str

Convert a WikiCoordinateType value to a plain str.

If ctype is a CoordinateType enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

ctype – coordinate type to convert

Returns:

string representation of the coordinate type

Examples:

from wikipediaapi import coordinate_type2str, CoordinateType

# Convert enum to string
assert coordinate_type2str(CoordinateType.ALL) == "all"
assert coordinate_type2str(CoordinateType.PRIMARY) == "primary"
assert coordinate_type2str(CoordinateType.SECONDARY) == "secondary"

# String pass-through (unchanged)
assert coordinate_type2str("all") == "all"
assert coordinate_type2str("primary") == "primary"
assert coordinate_type2str("secondary") == "secondary"

# Custom values pass through
assert coordinate_type2str("custom") == "custom"
class wikipediaapi.CoordinatesProp(*values)

Property values for coordinates query methods.

This enum is used by coordinates and batch_coordinates methods in both sync and async APIs to specify which additional coordinate properties to return from the MediaWiki API.

COUNTRY = 'country'

ISO 3166-1 alpha-2 country code (e.g. US or RU).

DIM = 'dim'

Approximate size of the object in meters.

GLOBE = 'globe'

Which terrestrial body coordinates are relative to (e.g. moon or pluto).

NAME = 'name'

Name of the object the coordinates point to.

REGION = 'region'

ISO 3166-2 region code (the part after the dash; e.g. FL or MOS).

TYPE = 'type'

Type of the object the coordinates point to.

wikipediaapi.coordinates_prop2str(prop: CoordinatesProp | str) → str

Convert a WikiCoordinatesProp value to a plain str.

If prop is a CoordinatesProp enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

prop – coordinates property to convert

Returns:

string representation of the coordinates property

Examples:

from wikipediaapi import coordinates_prop2str, CoordinatesProp

# Convert enum to string
assert coordinates_prop2str(CoordinatesProp.GLOBE) == "globe"
assert coordinates_prop2str(CoordinatesProp.COUNTRY) == "country"
assert coordinates_prop2str(CoordinatesProp.DIM) == "dim"
assert coordinates_prop2str(CoordinatesProp.NAME) == "name"
assert coordinates_prop2str(CoordinatesProp.REGION) == "region"
assert coordinates_prop2str(CoordinatesProp.TYPE) == "type"

# String pass-through (unchanged)
assert coordinates_prop2str("globe") == "globe"
assert coordinates_prop2str("country") == "country"
assert coordinates_prop2str("dim") == "dim"
assert coordinates_prop2str("name") == "name"
assert coordinates_prop2str("region") == "region"
assert coordinates_prop2str("type") == "type"

# Custom values pass through
assert coordinates_prop2str("custom") == "custom"
class wikipediaapi.GeoSearchSort(*values)

Sort values for geosearch method.

wikipediaapi.geosearch_sort2str(sort: GeoSearchSort | str) → str

Convert a WikiGeoSearchSort value to a plain str.

If sort is a GeoSearchSort enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

sort – geosearch sort direction to convert

Returns:

string representation of the sort direction

Examples:

from wikipediaapi import geosearch_sort2str, GeoSearchSort

# Convert enum to string
assert geosearch_sort2str(GeoSearchSort.DISTANCE) == "distance"

# String pass-through (unchanged)
assert geosearch_sort2str("distance") == "distance"

# Custom values pass through
assert geosearch_sort2str("custom") == "custom"
class wikipediaapi.Globe(*values)

Globe values for geosearch and coordinates methods.

This enum is used by geosearch and coordinates methods in both sync and async APIs.

wikipediaapi.globe2str(globe: Globe | str) → str

Convert a WikiGlobe value to a plain str.

If globe is a Globe enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

globe – globe to convert

Returns:

string representation of the globe

Examples:

from wikipediaapi import globe2str, Globe

# Convert enum to string
assert globe2str(Globe.EARTH) == "earth"

# String pass-through (unchanged)
assert globe2str("earth") == "earth"

# Custom values pass through
assert globe2str("custom") == "custom"
wikipediaapi.namespace2int(ns: Namespace | int) → int

Convert a WikiNamespace value to a plain int.

If ns is a Namespace enum member its integer value is returned. If it is already an int it is returned unchanged.

Parameters:

ns – namespace to convert

Returns:

integer representation of the namespace

Examples:

from wikipediaapi import namespace2int, Namespace

# Convert enum to int
assert namespace2int(Namespace.MAIN) == 0
assert namespace2int(Namespace.TALK) == 1
assert namespace2int(Namespace.USER) == 2

# String pass-through (unchanged)
assert namespace2int(0) == 0
assert namespace2int(1) == 1
assert namespace2int(2) == 2

# Custom values pass through
assert namespace2int("custom") == "custom"
class wikipediaapi.RedirectFilter(*values)

Filter redirect values for methods like random.

This enum is used by random and batch_random methods in both sync and async APIs.

wikipediaapi.redirect_filter2str(rfilter: RedirectFilter | str) → str

Convert a WikiRedirectFilter value to a plain str.

If rfilter is a RedirectFilter enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

rfilter – redirect filter to convert

Returns:

string representation of the redirect filter

Examples:

from wikipediaapi import redirect_filter2str, RedirectFilter

# Convert enum to string
assert redirect_filter2str(RedirectFilter.ALL) == "all"
assert redirect_filter2str(RedirectFilter.NONREDIRECTS) == "nonredirects"
assert redirect_filter2str(RedirectFilter.REDIRECTS) == "redirects"

# String pass-through (unchanged)
assert redirect_filter2str("all") == "all"
assert redirect_filter2str("nonredirects") == "nonredirects"
assert redirect_filter2str("redirects") == "redirects"

# Custom values pass through
assert redirect_filter2str("custom") == "custom"
class wikipediaapi.SearchInfo(*values)

Metadata values for search query methods.

This enum is used by the search method in both sync and async clients to specify which metadata to include in search results.

REWRITTEN_QUERY = 'rewrittenquery'

The rewritten/normalized search query used by the engine.

SUGGESTION = 'suggestion'

Spelling suggestion for alternative search terms.

TOTAL_HITS = 'totalhits'

Total number of matches found for the search query.

wikipediaapi.search_info2str(info: SearchInfo | str) → str

Convert a WikiSearchInfo value to a plain str.

If info is a SearchInfo enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

info – search info to convert

Returns:

string representation of the search info

Examples:

from wikipediaapi import search_info2str, SearchInfo

# Convert enum to string
assert search_info2str(SearchInfo.REWRITTEN_QUERY) == "rewrittenquery"
assert search_info2str(SearchInfo.SUGGESTION) == "suggestion"
assert search_info2str(SearchInfo.TOTAL_HITS) == "totalhits"

# String pass-through (unchanged)
assert search_info2str("rewrittenquery") == "rewrittenquery"
assert search_info2str("suggestion") == "suggestion"
assert search_info2str("totalhits") == "totalhits"

# Custom values pass through
assert search_info2str("custom") == "custom"
class wikipediaapi.SearchProp(*values)

Property values for search query methods.

This enum is used by the search method in both sync and async clients to specify which properties to include in search results. The srprop parameter is deprecated upstream but still supported.

SIZE = 'size'

Adds the size of the page in bytes.

WORDCOUNT = 'wordcount'

Adds the word count of the page.

TIMESTAMP = 'timestamp'

Adds the timestamp of when the page was last edited.

SNIPPET = 'snippet'

Adds a snippet of the page with query term highlighting markup.

TITLE_SNIPPET = 'titlesnippet'

Adds the page title with query term highlighting markup.

REDIRECT_TITLE = 'redirecttitle'

Adds the title of the matching redirect.

REDIRECT_SNIPPET = 'redirectsnippet'

Adds the title of the matching redirect with highlighting.

SECTION_TITLE = 'sectiontitle'

Adds the title of the matching section.

SECTION_SNIPPET = 'sectionsnippet'

Adds the title of the matching section with highlighting.

IS_FILE_MATCH = 'isfilematch'

Adds a boolean indicating if the search matched file content.

CATEGORY_SNIPPET = 'categorysnippet'

Adds the matching category name with highlighting.

SCORE = 'score'

Relevance score (deprecated upstream, ignored).

Has related suggestions (deprecated upstream, ignored).

EXTENSION_DATA = 'extensiondata'

Adds extra data generated by extensions.

wikipediaapi.search_prop2str(prop: SearchProp | str) → str

Convert a WikiSearchProp value to a plain str.

If prop is a SearchProp enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

prop – search property to convert

Returns:

string representation of the search property

Examples:

from wikipediaapi import search_prop2str, SearchProp

# Convert enum to string
assert search_prop2str(SearchProp.SIZE) == "size"
assert search_prop2str(SearchProp.WORDCOUNT) == "wordcount"
assert search_prop2str(SearchProp.TIMESTAMP) == "timestamp"
assert search_prop2str(SearchProp.SNIPPET) == "snippet"
assert search_prop2str(SearchProp.TITLE_SNIPPET) == "titlesnippet"
assert search_prop2str(SearchProp.REDIRECT_TITLE) == "redirecttitle"
assert search_prop2str(SearchProp.REDIRECT_SNIPPET) == "redirectsnippet"
assert search_prop2str(SearchProp.SECTION_TITLE) == "sectiontitle"
assert search_prop2str(SearchProp.SECTION_SNIPPET) == "sectionsnippet"
assert search_prop2str(SearchProp.IS_FILE_MATCH) == "isfilematch"
assert search_prop2str(SearchProp.CATEGORY_SNIPPET) == "categorysnippet"
assert search_prop2str(SearchProp.SCORE) == "score"
assert search_prop2str(SearchProp.HAS_RELATED) == "hasrelated"
assert search_prop2str(SearchProp.EXTENSION_DATA) == "extensiondata"

# String pass-through (unchanged)
assert search_prop2str("size") == "size"
assert search_prop2str("wordcount") == "wordcount"
assert search_prop2str("timestamp") == "timestamp"
assert search_prop2str("snippet") == "snippet"
assert search_prop2str("titlesnippet") == "titlesnippet"
assert search_prop2str("redirecttitle") == "redirecttitle"
assert search_prop2str("redirectsnippet") == "redirectsnippet"
assert search_prop2str("sectiontitle") == "sectiontitle"
assert search_prop2str("sectionsnippet") == "sectionsnippet"
assert search_prop2str("isfilematch") == "isfilematch"
assert search_prop2str("categorysnippet") == "categorysnippet"
assert search_prop2str("score") == "score"
assert search_prop2str("hasrelated") == "hasrelated"
assert search_prop2str("extensiondata") == "extensiondata"

# Custom values pass through
assert search_prop2str("custom") == "custom"
class wikipediaapi.SearchQiProfile(*values)

Query-independent profile values for search query methods.

This enum is used by the search method in both sync and async clients to specify the query-independent ranking profile to use.

CLASSIC = 'classic'

Classic ranking profile based on traditional factors.

Classic ranking without link boost factors.

EMPTY = 'empty'

Empty profile (debug only, no ranking applied).

ENGINE_AUTO_SELECT = 'engine_autoselect'

Let the search engine automatically select the best profile (default).

GROWTH_UNDERLINKED = 'growth_underlinked'

Prioritize underlinked articles for growth.

MLR_1024RS = 'mlr-1024rs'

Machine learning ranking model (1024 features).

MLR_1024RS_NEXT = 'mlr-1024rs-next'

Next generation machine learning ranking model.

Prioritize popular pages with many incoming links.

Weighted sum of links and pageviews for popular pages.

Weighted sum of links and pageviews.

Weighted sum of links and pageviews (alternative version).

wikipediaapi.search_qi_profile2str(qi_profile: SearchQiProfile | str) → str

Convert a WikiSearchQiProfile value to a plain str.

If qi_profile is a SearchQiProfile enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

qi_profile – search qi profile to convert

Returns:

string representation of the search qi profile

Examples:

from wikipediaapi import search_qi_profile2str, SearchQiProfile

# Convert enum to string
assert search_qi_profile2str(SearchQiProfile.CLASSIC) == "classic"
assert search_qi_profile2str(SearchQiProfile.ENGINE_AUTO_SELECT) == "engine_autoselect"

# String pass-through (unchanged)
assert search_qi_profile2str("classic") == "classic"
assert search_qi_profile2str("engine_autoselect") == "engine_autoselect"

# Custom values pass through
assert search_qi_profile2str("custom") == "custom"
class wikipediaapi.SearchSort(*values)

Sort values for search method.

wikipediaapi.search_sort2str(sort: SearchSort | str) → str

Convert a WikiSearchSort value to a plain str.

If sort is a SearchSort enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

sort – sort direction to convert

Returns:

string representation of the sort direction

Examples:

from wikipediaapi import search_sort2str, SearchSort

# Convert enum to string
assert search_sort2str(SearchSort.RELEVANCE) == "relevance"

# String pass-through (unchanged)
assert search_sort2str("relevance") == "relevance"

# Custom values pass through
assert search_sort2str("custom") == "custom"
class wikipediaapi.SearchWhat(*values)

Search type values for search query methods.

This enum is used by the search method in both sync and async clients to specify which type of search to perform.

NEAR_MATCH = 'nearmatch'

Near match for typos (finds pages with similar titles).

TEXT = 'text'

Search page text content (default, full-text search).

TITLE = 'title'

Search page titles only (asterisk, title-only matching).

wikipediaapi.search_what2str(what: SearchWhat | str) → str

Convert a WikiSearchWhat value to a plain str.

If what is a SearchWhat enum member its string value is returned. If it is already a str it is returned unchanged.

Parameters:

what – search what to convert

Returns:

string representation of the search what

Examples:

from wikipediaapi import search_what2str, SearchWhat

# Convert enum to string
assert search_what2str(SearchWhat.NEAR_MATCH) == "nearmatch"
assert search_what2str(SearchWhat.TEXT) == "text"
assert search_what2str(SearchWhat.TITLE) == "title"

# String pass-through (unchanged)
assert search_what2str("nearmatch") == "nearmatch"
assert search_what2str("text") == "text"
assert search_what2str("title") == "title"

# Custom values pass through
assert search_what2str("custom") == "custom"

Clients

class wikipediaapi.Wikipedia(*args: Any, **kwargs: Any)

Synchronous client for the Wikipedia API.

Combines WikipediaResource (public API methods) and SyncHTTPClient (blocking httpx transport with tenacity retry logic) via multiple inheritance.

All constructor parameters are forwarded to BaseHTTPClient.

Example usage:

import wikipediaapi

wiki = wikipediaapi.Wikipedia(
    user_agent='MyProject/1.0 (contact@example.com)',
    language='en',
)
page = wiki.page('Python_(programming_language)')
print(page.summary[:200])
Parameters:

  • user_agent – HTTP User-Agent string identifying your project. Must be at least 5 characters long. See https://meta.wikimedia.org/wiki/User-Agent_policy.

  • language – two-letter (or short) Wikipedia language code, e.g. "en", "de", "fr". See http://meta.wikimedia.org/wiki/List_of_Wikipedias.

  • variant – optional language variant for automatic conversion, e.g. "zh-tw"; None disables conversion.

  • extract_format – controls markup format of extracted text; defaults to WIKI.

  • headers – extra HTTP request headers merged with the auto-generated User-Agent.

  • extra_api_params – extra query-string parameters appended to every API call (e.g. {"converttitles": 1}).

  • max_retries – maximum number of retry attempts for transient errors (HTTP 429, 5xx, timeouts, connection errors). Set to 0 to disable retries entirely. Defaults to 3.

  • retry_wait – base wait time in seconds between retries; actual wait uses exponential backoff (retry_wait * 2 ** attempt). For HTTP 429 the Retry-After header value is used instead. Defaults to 1.0.

  • kwargs – additional keyword arguments forwarded to httpx.Client (e.g. timeout=30.0, proxies={…}, verify=False). Advanced Usage: These provide direct access to httpx capabilities. For most use cases, prefer the standard parameters above. Use httpx parameters only for specific requirements like custom proxies, SSL configuration, or connection pooling.

class wikipediaapi.AsyncWikipedia(*args: Any, **kwargs: Any)

Asynchronous client for the Wikipedia API.

Combines AsyncWikipediaResource (public async API methods) and AsyncHTTPClient (non-blocking httpx transport with tenacity retry logic) via multiple inheritance.

All constructor parameters are forwarded to BaseHTTPClient.

Unlike Wikipedia, the page object returned by page() is an AsyncWikipediaPage whose data-fetching methods are coroutines and must be await-ed.

Example usage:

import asyncio
import wikipediaapi

async def main():
    wiki = wikipediaapi.AsyncWikipedia(
        user_agent='MyProject/1.0 (contact@example.com)',
        language='en',
    )
    page = wiki.page('Python_(programming_language)')
    print(await page.summary)

asyncio.run(main())
Parameters:

  • user_agent – HTTP User-Agent string identifying your project. Must be at least 5 characters long. See https://meta.wikimedia.org/wiki/User-Agent_policy.

  • language – two-letter (or short) Wikipedia language code, e.g. "en", "de", "fr". See http://meta.wikimedia.org/wiki/List_of_Wikipedias.

  • variant – optional language variant for automatic conversion, e.g. "zh-tw"; None disables conversion.

  • extract_format – controls markup format of extracted text; defaults to WIKI.

  • headers – extra HTTP request headers merged with the auto-generated User-Agent.

  • extra_api_params – extra query-string parameters appended to every API call (e.g. {"converttitles": 1}).

  • max_retries – maximum number of retry attempts for transient errors (HTTP 429, 5xx, timeouts, connection errors). Set to 0 to disable retries entirely. Defaults to 3.

  • retry_wait – base wait time in seconds between retries; actual wait uses exponential backoff (retry_wait * 2 ** attempt). For HTTP 429 the Retry-After header value is used instead. Defaults to 1.0.

  • kwargs – additional keyword arguments forwarded to httpx.AsyncClient (e.g. timeout=30.0, proxies={…}, verify=False). Advanced Usage: These provide direct access to httpx capabilities. For most use cases, prefer the standard parameters above. Use httpx parameters only for specific requirements like custom proxies, SSL configuration, or connection pooling.

Pages

class wikipediaapi.WikipediaPage(wiki: Any, title: str, ns: Namespace | int = Namespace.MAIN, language: str = 'en', variant: str | None = None, url: str | None = None)

Lazy representation of a Wikipedia page.

A WikipediaPage is created by page() and requires no network call at construction time. Data is fetched from the MediaWiki API on demand: accessing a property triggers the minimum API call needed to populate it, and the result is cached so subsequent accesses are free.

Named properties (always available without a network call):

Attr language:

two-letter language code this page belongs to

Attr variant:

language variant used for auto-conversion, or None

Attr title:

page title as passed to page()

Attr namespace:

integer namespace number (0 = main article)

Dynamically resolved attributes (fetched lazily via ATTRIBUTES_MAPPING; trigger an info or extracts call on first access):

  • pageid — MediaWiki page ID (negative for missing pages)

  • fullurl — canonical read URL of the page

  • canonicalurl — canonical URL

  • editurl — URL for editing the page

  • displaytitle — formatted display title

  • talkid — ID of the associated talk page

  • lastrevid — ID of the most recent revision

  • length — page size in bytes

  • touched — timestamp of the last cache invalidation

  • contentmodel, pagelanguage, pagelanguagehtmlcode, pagelanguagedir, protection, restrictiontypes, watchers, visitingwatchers, notificationtimestamp, readable, preload, varianttitles

Map of page titles to stub pages that link to this page.

All backlinks are fetched with automatic pagination. Triggers a backlinks API call on first access.

API reference:

Returns:

{title: WikipediaPage} dict

property canonicalurl: Any

Canonical URL of the page.

property categories: PagesDict

Map of category titles to stub category pages for this page.

Keys include the Category: prefix. Triggers a categories API call on first access.

API reference:

Returns:

{title: WikipediaPage} dict

property categorymembers: PagesDict

Map of page titles to stub pages belonging to this category.

Only meaningful when self.namespace == Namespace.CATEGORY. Fetched with automatic pagination. Triggers a categorymembers API call on first access.

API reference:

Returns:

{title: WikipediaPage} dict

property contentmodel: Any

Content model of the page (e.g. "wikitext").

property coordinates: list[Coordinate]

Geographic coordinates associated with this page.

Triggers a coordinates API call on first access using default parameters. Subsequent accesses return the cached value. Use wiki.coordinates(page, primary="all") for non-default params.

Returns:

List of Coordinate objects; empty list if the page has no coordinates or does not exist.

property displaytitle: Any

Return the formatted display title (may differ from title in casing).

property editurl: Any

URL for editing the page in the browser.

exists() → bool

Return True if this page exists on Wikipedia.

Triggers an info API call on first invocation (via pageid attribute resolution) and caches the result. A negative pageid indicates a missing page.

Returns:

True if the page exists, False otherwise

property fullurl: Any

Canonical read URL of the page.

property geosearch_meta: GeoSearchMeta | None

Contextual metadata from a geosearch query, or None.

Set automatically when this page was returned by wiki.geosearch(). Contains distance, latitude, longitude, and primary flag from the search result.

Returns:

GeoSearchMeta if the page came from a geosearch query, None otherwise.

property images: ImagesDict

Images (files) used on this page.

Triggers an images API call on first access using default parameters. Subsequent accesses return the cached value. Use wiki.images(page, limit=50) for non-default params.

Returns:

ImagesDict keyed by image title; empty if the page has no images or does not exist.

Map of language codes to corresponding pages in other Wikipedias.

Keys are two-letter language codes (e.g. "de", "fr"), values are stub WikipediaPage objects with their language and fullurl pre-set. Triggers a langlinks API call on first access.

API reference:

Returns:

{language_code: WikipediaPage} dict

property lastrevid: Any

Revision ID of the most recent edit.

property length: Any

Page size in bytes.

Map of page titles to stub pages linked from this page.

All inter-wiki links are included, with automatic pagination so the complete set is always returned. Triggers a links API call on first access.

API reference:

Returns:

{title: WikipediaPage} dict

property notificationtimestamp: Any

Timestamp of the last change that triggered a notification.

property pageid: Any

MediaWiki numeric page ID (negative for missing pages).

property pagelanguage: Any

BCP-47 language code of the page content.

property pagelanguagedir: Any

Text directionality of the page language ("ltr" or "rtl").

property pagelanguagehtmlcode: Any

HTML lang attribute value for the page language.

property preload: Any

Preload template name if set, otherwise None.

property protection: Any

List of active protection descriptors (type, level, expiry).

property readable: Any

Non-empty string if the page is readable by the current user.

property restrictiontypes: Any

List of protection types applicable to this page.

property search_meta: SearchMeta | None

Contextual metadata from a search query, or None.

Set automatically when this page was returned by wiki.search(). Contains snippet, size, wordcount, and timestamp from the search result.

Returns:

SearchMeta if the page came from a search query, None otherwise.

property sections: list[WikipediaPageSection]

Top-level sections of this page.

Each element is a WikipediaPageSection that may contain its own child sections. Triggers an extracts call on first access.

Returns:

list of top-level WikipediaPageSection objects (may be empty for pages with no sections)

sections_by_title(title: str) → list[WikipediaPageSection]

Return all sections on this page whose heading matches title.

Overrides the base implementation to trigger an extracts fetch automatically on first call, so callers need not fetch sections explicitly.

Parameters:

title – exact heading text to look up

Returns:

list of matching WikipediaPageSection objects; empty list if no section with that title exists

property summary: str

Introductory text of this page (the content before the first section).

Triggers an extracts API call on first access; subsequent accesses return the cached value. Returns an empty string for pages that do not exist.

Returns:

plain-text or HTML summary string depending on wiki.extract_format

property talkid: Any

Page ID of the associated talk page.

property text: str

Full text of this page: summary followed by all sections.

Assembles the text by concatenating summary with the full_text() of every top-level section. The result is stripped of leading/trailing whitespace.

Triggers an extracts call on first access.

Returns:

complete page text as a single string

property touched: Any

ISO 8601 timestamp of the last cache invalidation.

property varianttitles: Any

Dict mapping variant codes to variant-specific titles.

property visitingwatchers: Any

Watchers who recently visited the page (may be None).

property watchers: Any

Number of users watching this page (may be None).

class wikipediaapi.AsyncWikipediaPage(wiki: Any, title: str, ns: Namespace | int = Namespace.MAIN, language: str = 'en', variant: str | None = None, url: str | None = None)

Lazy representation of a Wikipedia page for use with AsyncWikipedia.

Mirrors WikipediaPage but exposes all

Mirrors WikipediaPage but exposes all data-fetching as awaitables instead of blocking properties. A page stub is created by page() with no network call; each awaitable fetches its data on the first await. and caches the result for subsequent accesses.

Named properties (always available without a network call):

attr language:

two-letter language code this page belongs to

attr variant:

language variant used for auto-conversion, or None

attr title:

page title as passed to page()

attr ns:

integer namespace number (0 = main article)

Awaitable data properties (each triggers a network call on the first await and caches the result):

  • await page.summary — introductory text

  • await page.sections — top-level sections

  • await page.langlinks — {lang: AsyncWikipediaPage} dict

  • await page.links — {title: AsyncWikipediaPage} dict

  • await page.backlinks — {title: AsyncWikipediaPage} dict

  • await page.categories — {title: AsyncWikipediaPage} dict

  • await page.categorymembers — {title: AsyncWikipediaPage} dict

Awaitable info attributes (populated via the info API call; see ATTRIBUTES_MAPPING):

  • await page.pageid, await page.fullurl, await page.canonicalurl, await page.editurl, await page.displaytitle, await page.talkid, await page.lastrevid, await page.length, await page.touched, await page.contentmodel, await page.pagelanguage, await page.pagelanguagehtmlcode, await page.pagelanguagedir, await page.protection, await page.restrictiontypes, await page.watchers, await page.visitingwatchers, await page.notificationtimestamp, await page.readable, await page.preload, await page.varianttitles

Awaitable: {title: AsyncWikipediaPage} dict of pages linking here.

property canonicalurl: Any

Awaitable: canonical URL of the page.

property categories: Any

Awaitable: {title: AsyncWikipediaPage} dict of categories.

property categorymembers: Any

Awaitable: {title: AsyncWikipediaPage} dict of category members.

property contentmodel: Any

Awaitable: content model of the page (e.g. "wikitext").

property coordinates: Any

Awaitable: geographic coordinates associated with this page.

Triggers a coordinates API call on first access using default parameters. Subsequent accesses return the cached value. Use await wiki.coordinates(page, primary="all") for non-default params.

Returns:

Coroutine resolving to a list of Coordinate objects.

property displaytitle: Any

Awaitable: formatted display title.

property editurl: Any

Awaitable: URL for editing the page in the browser.

async exists() → bool

Return True if this page exists on Wikipedia.

Lazily fetches pageid via the info API call on the first await (identical approach to await page.fullurl). No prior data-fetching call is required:

exists = await page.exists()
Returns:

True if the page has a positive pageid; False otherwise

Raises:
property fullurl: Any

Awaitable: canonical read URL of the page.

property geosearch_meta: GeoSearchMeta | None

Contextual metadata from a geosearch query, or None.

Set automatically when this page was returned by await wiki.geosearch(). No network call needed.

Returns:

GeoSearchMeta if the page came from a geosearch query, None otherwise.

property images: Any

Awaitable: images (files) used on this page.

Triggers an images API call on first access using default parameters. Subsequent accesses return the cached value. Use await wiki.images(page, limit=50) for non-default params.

Returns:

Coroutine resolving to an AsyncImagesDict keyed by image title.

Awaitable: {language_code: AsyncWikipediaPage} dict.

property lastrevid: Any

Awaitable: revision ID of the most recent edit.

property length: Any

Awaitable: page size in bytes.

Awaitable: {title: AsyncWikipediaPage} dict of outbound links.

property notificationtimestamp: Any

Awaitable: timestamp of the last change that triggered a notification.

property pageid: Any

Awaitable: MediaWiki numeric page ID (negative for missing pages).

property pagelanguage: Any

Awaitable: BCP-47 language code of the page content.

property pagelanguagedir: Any

Awaitable: text directionality of the page language.

property pagelanguagehtmlcode: Any

Awaitable: HTML lang attribute value for the page language.

property preload: Any

Awaitable: preload template name if set, otherwise None.

property protection: Any

Awaitable: list of active protection descriptors.

property readable: Any

Awaitable: non-empty string if the page is readable by the current user.

property restrictiontypes: Any

Awaitable: list of protection types applicable to this page.

property search_meta: SearchMeta | None

Contextual metadata from a search query, or None.

Set automatically when this page was returned by await wiki.search(). No network call needed.

Returns:

SearchMeta if the page came from a search query, None otherwise.

property sections: Any

Awaitable: top-level sections of this page.

property summary: Any

Awaitable: introductory text of this page (before the first section).

property talkid: Any

Awaitable: page ID of the associated talk page.

property text: Any

Awaitable: full page text — summary followed by all sections.

property touched: Any

Awaitable: ISO 8601 timestamp of the last cache invalidation.

property varianttitles: Any

Awaitable: dict mapping variant codes to variant-specific titles.

property visitingwatchers: Any

Awaitable: watchers who recently visited the page (may be None).

property watchers: Any

Awaitable: number of users watching this page (may be None).

class wikipediaapi.WikipediaPageSection(wiki: BaseWikipediaResource, title: str, level: int = 0, text: str = '')

Represents a single section (or the root summary) of a Wikipedia page.

Sections are arranged in a tree: each section may have zero or more child sections accessible via sections. The root of the tree is the page summary (level 0); its children are top-level headings (level 2 for ==Heading== / <h2>); their children are sub-headings, and so on.

Instances are created by _build_extracts() and should not normally be constructed directly.

Attr wiki:

the Wikipedia instance used to determine the extract format when rendering

full_text(level: int = 1) → str

Return the rendered text of this section and all its descendants.

The heading is prepended in the format appropriate for wiki.extract_format:

Sub-sections are appended recursively with level incremented by one for each nesting depth.

Parameters:

level – heading depth to use for this section’s heading; child sections use level + 1, etc. Callers typically pass 2 for a top-level section.

Returns:

full rendered string including heading, body, and all descendant sections

Raises:

NotImplementedError – if wiki.extract_format is not ExtractFormat.WIKI or ExtractFormat.HTML

property level: int

Heading depth of this section.

The summary pseudo-section has level 0. Heading levels follow the HTML convention: 2 for the outermost heading (==...== / <h2>), 3 for the next level, and so on.

Returns:

integer heading level (0 = summary, 2 = top-level, …)

section_by_title(title: str) → WikipediaPageSection | None

Return the last direct child section whose heading matches title.

When multiple sub-sections share the same heading (rare but valid in Wikipedia) the last one is returned. Returns None if no matching child section exists.

Parameters:

title – exact heading text to search for

Returns:

the matching WikipediaPageSection, or None

property sections: list[WikipediaPageSection]

Direct child sections of this section.

Each element is itself a WikipediaPageSection that may have further children. Use recursion to traverse the full tree.

Returns:

list of immediate sub-sections (may be empty)

property text: str

Body text of this section, excluding heading and sub-sections.

The format (plain wiki markup or HTML) matches the extract_format of the Wikipedia instance that fetched the page.

Returns:

section body text as a string

property title: str

Heading text of this section.

For the root / summary pseudo-section this is an empty string.

Returns:

section heading as a plain string

Enums & Types

class wikipediaapi.ExtractFormat(*values)

Controls the markup format used when fetching page extracts.

Pass a value of this enum as the extract_format argument to Wikipedia or AsyncWikipedia. The chosen format affects how section headers are recognised, how text is structured, and what markup characters appear in the returned strings.

Example usage:

import wikipediaapi
wiki = wikipediaapi.Wikipedia(
    user_agent='MyBot/1.0',
    language='en',
    extract_format=wikipediaapi.ExtractFormat.HTML,
)
WIKI = 1

Plain-text wiki markup format.

Section headings are represented as ==Title==, ===Title===, etc., allowing the library to recognise and split on them. Best choice when you only need the textual content without any HTML.

MediaWiki API reference: https://www.mediawiki.org/wiki/Extension:TextExtracts

HTML = 2

HTML format.

Section headings are represented as <h2>, <h3>, etc., and body text is wrapped in <p> tags. Use this format when you need to render the content in a browser or HTML-aware renderer.

MediaWiki API reference: https://www.mediawiki.org/wiki/Extension:TextExtracts

class wikipediaapi.Namespace(*values)

Integer enumeration of MediaWiki namespaces.

Each Wikipedia page belongs to a namespace identified by an integer. Namespace 0 (MAIN) contains ordinary articles; other values represent talk pages, user pages, category pages, etc.

Pass a member of this enum wherever a WikiNamespace is accepted (e.g. wiki.page("Python", ns=Namespace.MAIN)).

Full namespace reference:

MAIN = 0

Main article namespace (ns=0). Ordinary Wikipedia articles live here.

TALK = 1

Talk namespace (ns=1). Discussion pages for main-namespace articles.

USER = 2

User namespace (ns=2). Pages belonging to registered users.

USER_TALK = 3

User talk namespace (ns=3). Discussion pages for user pages.

WIKIPEDIA = 4

Wikipedia project namespace (ns=4). Policy and project pages.

WIKIPEDIA_TALK = 5

Wikipedia talk namespace (ns=5). Discussion of project pages.

FILE = 6

File namespace (ns=6). Images, audio files, and other media.

FILE_TALK = 7

File talk namespace (ns=7). Discussion of file pages.

MEDIAWIKI = 8

MediaWiki namespace (ns=8). Interface messages and system texts.

MEDIAWIKI_TALK = 9

MediaWiki talk namespace (ns=9). Discussion of interface messages.

TEMPLATE = 10

Template namespace (ns=10). Reusable wiki templates.

TEMPLATE_TALK = 11

Template talk namespace (ns=11). Discussion of templates.

HELP = 12

Help namespace (ns=12). Help and how-to pages.

HELP_TALK = 13

Help talk namespace (ns=13). Discussion of help pages.

CATEGORY = 14

Category namespace (ns=14). Category pages that group articles.

CATEGORY_TALK = 15

Category talk namespace (ns=15). Discussion of category pages.

PORTAL = 100

Portal namespace (ns=100). Topic-focused entry-point portals.

PORTAL_TALK = 101

Portal talk namespace (ns=101). Discussion of portals.

PROJECT = 102

Project namespace (ns=102). WikiProject coordination pages.

PROJECT_TALK = 103

Project talk namespace (ns=103). Discussion of WikiProject pages.

REFERENCE = 104

Reference namespace (ns=104). Reference desk pages.

REFERENCE_TALK = 105

Reference talk namespace (ns=105). Discussion of reference pages.

BOOK = 108

Book namespace (ns=108). Wikipedia book pages.

BOOK_TALK = 109

Book talk namespace (ns=109). Discussion of book pages.

DRAFT = 118

Draft namespace (ns=118). Unreviewed draft articles.

DRAFT_TALK = 119

Draft talk namespace (ns=119). Discussion of draft pages.

EDUCATION_PROGRAM = 446

Education Program namespace (ns=446). Educational course pages.

EDUCATION_PROGRAM_TALK = 447

Education Program talk namespace (ns=447).

TIMED_TEXT = 710

TimedText namespace (ns=710). Subtitle/caption files for media.

TIMED_TEXT_TALK = 711

TimedText talk namespace (ns=711). Discussion of timed-text pages.

MODULE = 828

Module namespace (ns=828). Lua scripting modules.

MODULE_TALK = 829

Module talk namespace (ns=829). Discussion of Lua modules.

GADGET = 2300

Gadget namespace (ns=2300). JavaScript gadget pages.

GADGET_TALK = 2301

Gadget talk namespace (ns=2301). Discussion of gadget pages.

GADGET_DEFINITION = 2302

Gadget definition namespace (ns=2302). Gadget definition pages.

GADGET_DEFINITION_TALK = 2303

Gadget definition talk namespace (ns=2303).

class wikipediaapi.Direction(*values)

Sort direction values for image query methods.

This enum is used by images and batch_images methods in both sync and async APIs.

class wikipediaapi.CoordinateType(*values)

Coordinate types for coordinates and geosearch methods.

This enum is used by coordinates and geosearch methods in both sync and async APIs to specify which type of coordinates to return.

ALL = 'all'

Return both primary and secondary coordinates.

PRIMARY = 'primary'

Return only primary coordinates (location of article subject).

SECONDARY = 'secondary'

Return only secondary coordinates (locations of objects mentioned in article).

class wikipediaapi.Globe(*values)

Globe values for geosearch and coordinates methods.

This enum is used by geosearch and coordinates methods in both sync and async APIs.

class wikipediaapi.SearchSort(*values)

Sort values for search method.

class wikipediaapi.GeoSearchSort(*values)

Sort values for geosearch method.

class wikipediaapi.RedirectFilter(*values)

Filter redirect values for methods like random.

This enum is used by random and batch_random methods in both sync and async APIs.

class wikipediaapi.SearchProp(*values)

Property values for search query methods.

This enum is used by the search method in both sync and async clients to specify which properties to include in search results. The srprop parameter is deprecated upstream but still supported.

SIZE = 'size'

Adds the size of the page in bytes.

WORDCOUNT = 'wordcount'

Adds the word count of the page.

TIMESTAMP = 'timestamp'

Adds the timestamp of when the page was last edited.

SNIPPET = 'snippet'

Adds a snippet of the page with query term highlighting markup.

TITLE_SNIPPET = 'titlesnippet'

Adds the page title with query term highlighting markup.

REDIRECT_TITLE = 'redirecttitle'

Adds the title of the matching redirect.

REDIRECT_SNIPPET = 'redirectsnippet'

Adds the title of the matching redirect with highlighting.

SECTION_TITLE = 'sectiontitle'

Adds the title of the matching section.

SECTION_SNIPPET = 'sectionsnippet'

Adds the title of the matching section with highlighting.

IS_FILE_MATCH = 'isfilematch'

Adds a boolean indicating if the search matched file content.

CATEGORY_SNIPPET = 'categorysnippet'

Adds the matching category name with highlighting.

SCORE = 'score'

Relevance score (deprecated upstream, ignored).

HAS_RELATED = 'hasrelated'

Has related suggestions (deprecated upstream, ignored).

EXTENSION_DATA = 'extensiondata'

Adds extra data generated by extensions.

class wikipediaapi.SearchInfo(*values)

Metadata values for search query methods.

This enum is used by the search method in both sync and async clients to specify which metadata to include in search results.

REWRITTEN_QUERY = 'rewrittenquery'

The rewritten/normalized search query used by the engine.

SUGGESTION = 'suggestion'

Spelling suggestion for alternative search terms.

TOTAL_HITS = 'totalhits'

Total number of matches found for the search query.

class wikipediaapi.SearchWhat(*values)

Search type values for search query methods.

This enum is used by the search method in both sync and async clients to specify which type of search to perform.

NEAR_MATCH = 'nearmatch'

Near match for typos (finds pages with similar titles).

TEXT = 'text'

Search page text content (default, full-text search).

TITLE = 'title'

Search page titles only (asterisk, title-only matching).

class wikipediaapi.SearchQiProfile(*values)

Query-independent profile values for search query methods.

This enum is used by the search method in both sync and async clients to specify the query-independent ranking profile to use.

CLASSIC = 'classic'

Classic ranking profile based on traditional factors.

CLASSIC_NO_BOOST_LINKS = 'classic_noboostlinks'

Classic ranking without link boost factors.

EMPTY = 'empty'

Empty profile (debug only, no ranking applied).

ENGINE_AUTO_SELECT = 'engine_autoselect'

Let the search engine automatically select the best profile (default).

GROWTH_UNDERLINKED = 'growth_underlinked'

Prioritize underlinked articles for growth.

MLR_1024RS = 'mlr-1024rs'

Machine learning ranking model (1024 features).

MLR_1024RS_NEXT = 'mlr-1024rs-next'

Next generation machine learning ranking model.

POPULAR_INCLINKS = 'popular_inclinks'

Prioritize popular pages with many incoming links.

POPULAR_INCLINKS_PV = 'popular_inclinks_pv'

Weighted sum of links and pageviews for popular pages.

WSUM_INCLINKS = 'wsum_inclinks'

Weighted sum of links and pageviews.

WSUM_INCLINKS_PV = 'wsum_inclinks_pv'

Weighted sum of links and pageviews (alternative version).

class wikipediaapi.CoordinatesProp(*values)

Property values for coordinates query methods.

This enum is used by coordinates and batch_coordinates methods in both sync and async APIs to specify which additional coordinate properties to return from the MediaWiki API.

COUNTRY = 'country'

ISO 3166-1 alpha-2 country code (e.g. US or RU).

DIM = 'dim'

Approximate size of the object in meters.

GLOBE = 'globe'

Which terrestrial body coordinates are relative to (e.g. moon or pluto).

NAME = 'name'

Name of the object the coordinates point to.

REGION = 'region'

ISO 3166-2 region code (the part after the dash; e.g. FL or MOS).

TYPE = 'type'

Type of the object the coordinates point to.

class wikipediaapi.GeoPoint(lat: float = 0.0, lon: float = 0.0)

A geographic point with latitude/longitude validation.

Used as pythonic input for API parameters that previously required MediaWiki’s "lat|lon" string format.

Args:

lat: Latitude in decimal degrees, valid range [-90.0, 90.0]. lon: Longitude in decimal degrees, valid range [-180.0, 180.0].

Raises:

ValueError: If lat is outside [-90.0, 90.0]. ValueError: If lon is outside [-180.0, 180.0].

to_mediawiki() → str

Convert this point to MediaWiki "lat|lon" format.

Returns:

The "lat|lon" string expected by MediaWiki query params.

class wikipediaapi.GeoBox(top_left: GeoPoint = GeoPoint(lat=0.0, lon=0.0), bottom_right: GeoPoint = GeoPoint(lat=0.0, lon=0.0))

A geographic bounding box defined by two validated corner points.

Represents MediaWiki’s gsbbox value in a pythonic structured way.

Args:

top_left: Top-left corner of box. bottom_right: Bottom-right corner of box.

Raises:

ValueError: If top-left latitude is smaller than bottom-right latitude. ValueError: If top-left longitude is greater than bottom-right longitude.

to_mediawiki() → str

Convert this box to MediaWiki "top|left|bottom|right" format.

Returns:

The "top_lat|left_lon|bottom_lat|right_lon" string expected by MediaWiki query params.

class wikipediaapi.Coordinate(lat: float, lon: float, primary: bool, globe: str = 'earth', type: str | None = None, name: str | None = None, dim: int | None = None, country: str | None = None, region: str | None = None, dist: float | None = None)

A single geographic coordinate associated with a Wikipedia page.

Represents one entry from prop=coordinates API response. Always contains lat, lon, and primary; additional fields are populated when requested via prop parameter.

Args:

lat: Latitude in decimal degrees. lon: Longitude in decimal degrees. primary: True if this is primary coordinate for page. globe: Celestial body coordinates refer to. type: Type of geographic object (e.g. "city"). name: Name of geographic object. dim: Approximate size of object in meters. country: ISO 3166-1 alpha-2 country code. region: ISO 3166-2 region code (part after dash). dist: Distance in meters from a reference point, set only when

distance_from_point or distance_from_page is used.

class wikipediaapi.GeoSearchMeta(dist: float, lat: float, lon: float, primary: bool)

Contextual metadata attached to pages returned by a geosearch query.

Accessible via page.geosearch_meta on pages produced by wiki.geosearch(). Contains distance from search centre and coordinate that was matched.

Args:

dist: Distance in meters from search centre. lat: Latitude of matched coordinate. lon: Longitude of matched coordinate. primary: True if matched coordinate is the primary one.

class wikipediaapi.SearchMeta(snippet: str = '', size: int = 0, wordcount: int = 0, timestamp: str = '')

Contextual metadata attached to pages returned by a search query.

Accessible via page.search_meta on pages produced by wiki.search(). Contains search-specific fields like highlighted snippet.

Args:

snippet: HTML snippet with query-term highlighting. size: Page size in bytes. wordcount: Word count of page. timestamp: ISO 8601 timestamp of last edit.

class wikipediaapi.SearchResults(pages: PagesDict, totalhits: int = 0, suggestion: str | None = None)

Wrapper for search results combining pages with aggregate metadata.

Returned by wiki.search(). The pages attribute is a PagesDict keyed by title; each page carries a SearchMeta sub-object accessible via page.search_meta.

Args:

pages: Dictionary of matching pages keyed by title. totalhits: Total number of matches reported by the API. suggestion: Spelling suggestion from search backend, or None.

class wikipediaapi.PagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Dictionary of WikipediaPage objects with batch methods.

Inherits from dict[str, WikipediaPage] and adds a reference to wiki client so that batch operations can be dispatched in a single API call per chunk of 50 pages.

Args:

wiki: The Wikipedia client instance. data: Optional initial mapping of {title: WikipediaPage}.

coordinates(*, limit: int = 10, primary: WikiCoordinateType = CoordinateType.PRIMARY, prop: Iterable[WikiCoordinatesProp] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: WikipediaPage | None = None) → dict[WikipediaPage, list[Coordinate]]

Batch-fetch coordinates for all pages in this dict.

Delegates to wiki.batch_coordinates() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum coordinates per page (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

{page: [Coordinate, ...]} for every page in this dict.

images(*, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, PagesDict]

Batch-fetch images for all pages in this dict.

Delegates to wiki.batch_images() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum images per page (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

{title: PagesDict} for every page in this dict.

class wikipediaapi.AsyncPagesDict(wiki: BaseWikipediaResource | None = None, data: Mapping[str, BaseWikipediaPage[Any]] | None = None)

Async dictionary of AsyncWikipediaPage objects with batch methods.

Async mirror of PagesDict. Batch methods are coroutines.

Args:

wiki: The AsyncWikipedia client instance. data: Optional initial mapping of {title: AsyncWikipediaPage}.

async coordinates(*, limit: int = 10, primary: WikiCoordinateType = CoordinateType.PRIMARY, prop: Iterable[WikiCoordinatesProp] = (CoordinatesProp.GLOBE,), distance_from_point: GeoPoint | None = None, distance_from_page: AsyncWikipediaPage | None = None) → dict[AsyncWikipediaPage, list[Coordinate]]

Async batch-fetch coordinates for all pages in this dict.

Delegates to wiki.batch_coordinates() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum coordinates per page (1–500). primary: Which coordinates: "primary", "secondary", "all". prop: Additional properties as an iterable. distance_from_point: Reference point as GeoPoint. distance_from_page: Reference page.

Returns:

{page: [Coordinate, ...]} for every page in this dict.

async images(*, limit: int = 10, images: Iterable[str] | None = None, direction: Direction | str = Direction.ASCENDING) → dict[str, PagesDict]

Async batch-fetch images for all pages in this dict.

Delegates to wiki.batch_images() which sends multi-title API requests (up to 50 titles per request).

Args:

limit: Maximum images per page (1–500). images: Specific images as an iterable. direction: Sort direction as WikiDirection.

Returns:

{title: PagesDict} for every page in this dict.

Exceptions

exception wikipediaapi.WikipediaException

Base exception for all Wikipedia-API errors.

All library-specific exceptions inherit from this class, so callers can catch every possible error with a single except clause:

try:
    page = wiki.page("Python")
    print(page.summary)
except wikipediaapi.WikipediaException as e:
    print(f"Wikipedia error: {e}")
exception wikipediaapi.WikiHttpTimeoutError(url: str)

Raised when a request to Wikipedia API times out.

Corresponds to httpx.TimeoutException from the underlying HTTP client. May be raised after all retry attempts are exhausted.

Attr url:

endpoint URL that timed out

exception wikipediaapi.WikiHttpError(status_code: int, url: str)

Raised when Wikipedia API returns a non-success HTTP status code.

4xx responses that are not 429 are raised immediately (no retry). 5xx responses are retried up to max_retries times and then raise this exception if they never succeed.

Attr status_code:

HTTP status code that was received

Attr url:

endpoint URL that returned error

exception wikipediaapi.WikiRateLimitError(url: str, retry_after: int | None = None)

Raised when Wikipedia API returns HTTP 429 (Too Many Requests).

Subclass of WikiHttpError with status_code always equal to 429. The retry_after attribute is populated from Retry-After response header when present; retry logic in BaseHTTPClient honours this value as wait time before the next attempt.

Attr retry_after:

seconds to wait before retrying, or None if Retry-After header was absent or non-numeric

Attr url:

endpoint URL that was rate-limited

exception wikipediaapi.WikiInvalidJsonError(url: str)

Raised when Wikipedia API returns a 200 response with invalid JSON.

This should not normally occur; if it does it may indicate a temporary server-side issue or a network proxy mangling the response body.

Attr url:

endpoint URL whose response could not be decoded

exception wikipediaapi.WikiConnectionError(url: str)

Raised when a network connection to Wikipedia API cannot be established.

Corresponds to httpx.ConnectError or any other httpx.RequestError that is not a timeout. May be raised after all retry attempts are exhausted.

Attr url:

endpoint URL that could not be reached