Client

The Client class is the main entry point for interacting with the OSRS Real-time Prices API.

osrs_prices.Client

Client(
    user_agent: str,
    timeout: float = DEFAULT_TIMEOUT,
    cache_ttl: float = DEFAULT_CACHE_TTL,
)

Client for the OSRS Real-time Prices API.

This client provides access to all OSRS Prices API endpoints with automatic caching for mapping data and proper User-Agent handling.

Example

with Client(user_agent="my-app/1.0") as client: ... mapping = client.get_mapping() ... prices = client.get_latest()

Initialize the client.

Parameters:

Name	Type	Description	Default
user_agent	str	A descriptive User-Agent string identifying your application. Must not be a generic library agent (e.g., "python-requests").	required
timeout	float	Request timeout in seconds.	DEFAULT_TIMEOUT
cache_ttl	float	Time-to-live for the mapping cache in seconds.	DEFAULT_CACHE_TTL

Raises:

Type	Description
ValidationError	If the user_agent is invalid or blocked.

__enter__

__enter__() -> Client

Enter the context manager.

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> None

Exit the context manager and close the HTTP client.

close

close() -> None

Close the HTTP client and release resources.

get_latest

get_latest(item_id: int | None = None) -> LatestResponse

Get the latest instant-buy and instant-sell prices.

Parameters:

Name	Type	Description	Default
item_id	int | None	Optional item ID to filter to a single item.	None

Returns:

Type	Description
LatestResponse	The latest price data.

get_mapping

get_mapping(force_refresh: bool = False) -> MappingResponse

Get item mapping data (metadata for all items).

This data is cached by default. Use force_refresh to bypass the cache.

Parameters:

Name	Type	Description	Default
force_refresh	bool	If True, bypass the cache and fetch fresh data.	False

Returns:

Type	Description
MappingResponse	The item mapping data.

get_5m_average

get_5m_average(
    timestamp: int | None = None,
) -> AverageResponse

Get 5-minute average prices.

Parameters:

Name	Type	Description	Default
timestamp	int | None	Optional Unix timestamp to get historical data. If not provided, returns the latest data.	None

Returns:

Type	Description
AverageResponse	The 5-minute average price data.

get_1h_average

get_1h_average(
    timestamp: int | None = None,
) -> AverageResponse

Get 1-hour average prices.

Parameters:

Name	Type	Description	Default
timestamp	int | None	Optional Unix timestamp to get historical data. If not provided, returns the latest data.	None

Returns:

Type	Description
AverageResponse	The 1-hour average price data.

get_timeseries

get_timeseries(
    item_id: int, timestep: Timestep
) -> TimeseriesResponse

Get historical timeseries data for an item.

Parameters:

Name	Type	Description	Default
item_id	int	The item ID to fetch data for.	required
timestep	Timestep	The time interval for data points ("5m", "1h", "6h", or "24h").	required

Returns:

Type	Description
TimeseriesResponse	The timeseries data.

invalidate_mapping_cache

invalidate_mapping_cache() -> None

Manually invalidate the mapping cache.

get_item_by_name

get_item_by_name(name: str) -> ItemMapping | None

Find an item by its exact name.

Parameters:

Name	Type	Description	Default
name	str	The exact item name to search for.	required

Returns:

Type	Description
ItemMapping | None	The item mapping if found, None otherwise.

get_latest_with_mapping

get_latest_with_mapping(
    item_id: int | None = None,
) -> EnrichedLatestResponse

Get latest prices enriched with item metadata.

Parameters:

Name	Type	Description	Default
item_id	int | None	Optional item ID to filter to a single item.	None

Returns:

Type	Description
EnrichedLatestResponse	Latest prices combined with item mapping data.

Example

with Client(user_agent="my-app/1.0") as client: ... enriched = client.get_latest_with_mapping() ... for item in enriched.items: ... print(f"{item.name}: {item.high} gp")

get_5m_average_with_mapping

get_5m_average_with_mapping(
    timestamp: int | None = None,
) -> EnrichedAverageResponse

Get 5-minute average prices enriched with item metadata.

Parameters:

Name	Type	Description	Default
timestamp	int | None	Optional Unix timestamp to get historical data.	None

Returns:

Type	Description
EnrichedAverageResponse	5-minute average prices combined with item mapping data.

get_1h_average_with_mapping

get_1h_average_with_mapping(
    timestamp: int | None = None,
) -> EnrichedAverageResponse

Get 1-hour average prices enriched with item metadata.

Parameters:

Name	Type	Description	Default
timestamp	int | None	Optional Unix timestamp to get historical data.	None

Returns:

Type	Description
EnrichedAverageResponse	1-hour average prices combined with item mapping data.

get_timeseries_with_mapping

get_timeseries_with_mapping(
    item_id: int, timestep: Timestep
) -> EnrichedTimeseriesResponse

Get timeseries data with item metadata attached.

Parameters:

Name	Type	Description	Default
item_id	int	The item ID to fetch data for.	required
timestep	Timestep	The time interval for data points ("5m", "1h", "6h", or "24h").	required

Returns:

Type	Description
EnrichedTimeseriesResponse	Timeseries data with the item's metadata.

Raises:

Type	Description
ValidationError	If the item_id is not found in the mapping.

enrich

enrich(response: LatestResponse) -> EnrichedLatestResponse

enrich(
    response: AverageResponse,
) -> EnrichedAverageResponse

enrich(
    response: TimeseriesResponse,
) -> EnrichedTimeseriesResponse

enrich(
    response: LatestResponse
    | AverageResponse
    | TimeseriesResponse,
) -> (
    EnrichedLatestResponse
    | EnrichedAverageResponse
    | EnrichedTimeseriesResponse
)

Enrich an existing response with item metadata.

This is a convenience method for users who already have a response and want to add item metadata to it.

Parameters:

Name	Type	Description	Default
response	LatestResponse | AverageResponse | TimeseriesResponse	A LatestResponse, AverageResponse, or TimeseriesResponse to enrich.	required

Returns:

Type	Description
EnrichedLatestResponse | EnrichedAverageResponse | EnrichedTimeseriesResponse	The enriched response with item metadata added.

Raises:

Type	Description
ValidationError	If enriching a TimeseriesResponse without an item_id.

Example

with Client(user_agent="my-app/1.0") as client: ... latest = client.get_latest() ... enriched = client.enrich(latest) ... for item in enriched.items: ... print(f"{item.name}: {item.high} gp")