bdomarket 0.3.2

API client for BDO market

bdomarket

API client for BDO market data
Explore the docs »
PyPI · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

This code is a simple and well-structured API client for BDO market data, built for convenience. It enables developers to access market information, price history, and shop data from Arsha.io in a standardized way.

Features

• Market Data Access: Retrieve real-time and historical data from the BDO Central Market, including waitlists, hotlists, item lists, sublists, search results, bidding info, and price info.
• Boss Timers: Easily fetch and display world boss spawn times for different servers and regions.
• Item Management: Query single or multiple items by ID, dump large ranges of item data, and work with item objects that support conversion to dictionaries and icon downloading.
• API Response Handling: All API calls return a standardized ApiResponse object, making it easy to access content, status codes, and success flags, as well as to deserialize responses into Python objects.
• Data Export: Save any API response directly to a file in JSON format for later analysis or debugging.
• Timestamp Conversion: Convert Unix timestamps from API responses into human-readable date and time strings.
• Multi-Region and Multi-Language Support: Easily switch between different BDO regions (EU, NA, etc.) and supported languages.
• Convenient Utilities: Download item icons, print readable representations of items, and more.
• Regional Pig Cave Status: Easily fetch pig cave status for different regions.

(back to top)

Get involved

Donate

If you like my project, you can buy me a coffee, many thanks ❤️ !

Built With

(back to top)

Getting Started

A Python API client for accessing the Arsha.io Black Desert Online Market API.

Easily retrieve market data, hotlist items, price history, bidding info, and more.

Prerequisites

Python installed on your system.

• Python >= 3.9

Installation

pip install bdomarket

(back to top)

Usage

Quick Start — ArshaMarket (async)

import asyncio
import bdomarket

async def main():
    async with bdomarket.Market(
        region=bdomarket.MarketRegion.EU,
        apiversion=bdomarket.ApiVersion.V2,
        language=bdomarket.Locale.English
    ) as market:
        # Wait list
        r = await market.get_world_market_wait_list()
        print(r.success, r.status_code)
        r.save_to_file("responses/waitlist.json")

        # Hot list
        r = await market.get_world_market_hot_list()
        r.save_to_file("responses/hotlist.json")

        # Price history (convertdate converts timestamps, formatprice adds separators)
        r = await market.get_market_price_info(
            ids=["735008", "735009"], sids=["20", "20"],
            convertdate=True, formatprice=False
        )
        r.save_to_file("responses/priceinfo.json")

        # Items by category (mainCategory=1 Weapons, subCategory=1 Swords)
        r = await market.get_world_market_list(main_category="1", sub_category="1")
        r.save_to_file("responses/marketlist.json")

        # Sub list — all enhancement levels for an item
        r = await market.get_world_market_sub_list(ids=["735008"])
        r.save_to_file("responses/sublist.json")

        # Bidding info — current buy/sell orders
        r = await market.get_bidding_info(ids=["735008", "735009"], sids=["20", "20"])
        r.save_to_file("responses/biddinginfo.json")

        # Pearl items
        r = await market.get_pearl_items()
        r.save_to_file("responses/pearlitems.json")

        # Full market snapshot
        r = await market.get_market()
        r.save_to_file("responses/market.json")

        # Item lookup
        r = await market.get_item(ids=["735008"])
        r.save_to_file("responses/item.json")

        # Item database dump (full)
        r = await market.item_database_dump_v2()
        r.save_to_file("responses/itemdump.json")
        if r.success and r.content:
            print(bdomarket.get_items_by_name_from_db(r.content, "Blackstar Shuriken"))
            print(bdomarket.get_items_by_id_from_db(r.content, 735008))

asyncio.run(main())

Sync usage — ArshaMarket

Every async method has a _sync counterpart. Pass Market(...) without async with and call .close() when done:

market = bdomarket.Market(
    region=bdomarket.MarketRegion.EU,
    apiversion=bdomarket.ApiVersion.V2,
    language=bdomarket.Locale.English
)

r = market.get_world_market_wait_list_sync()
r.save_to_file("responses/waitlist.json")

r = market.get_bidding_info_sync(ids=["735008", "735009"], sids=["20", "20"])
r.save_to_file("responses/biddinginfo.json")

# ... all other _sync methods follow the same pattern ...

market.close()

UnofficialMarket

import asyncio
import bdomarket

async def main():
    async with bdomarket.UnofficialMarket(
        region=bdomarket.MarketRegion.EU,
        language=bdomarket.Locale.English
    ) as u:
        # Queue list (items awaiting listing)
        r = await u.get_list_queue()
        print(r.success, r.status_code)

        # Items by category
        r = await u.get_list_category(main_category=20, sub_category=1)

        # Item details by ID
        r = await u.get_item_id(item_id=12094)
        if r.success:
            print(r.content.get("name"), r.content.get("grade"))

        # Item icon (returns raw PNG bytes)
        r = await u.get_item_id_icon(item_id=12094)
        if r.success:
            r.save_image("responses/icons/12094.png")

        # Enhancement details and tooltip
        r = await u.get_item_id_enhancement(item_id=12094, enhancement=5)
        r = await u.get_item_id_enhancement_tooltip(item_id=12094, enhancement=5)

        # Search by name
        r = await u.get_search(search_string="Deboreka Ring")
        if r.success:
            print(f"Found {len(r.content)} result(s)")

asyncio.run(main())

All UnofficialMarket methods also have _sync variants (e.g. get_list_queue_sync(), get_item_id_sync(), get_search_sync()).

Boss Timer

import bdomarket

boss = bdomarket.Boss(server=bdomarket.Server.EU).scrape()
print(boss.get_timer())          # list of dicts
print(boss.get_timer_json())     # JSON string

Item Icon Downloader

import bdomarket

item = bdomarket.Item(item_id="735008", name="Blackstar Shuriken")

# Save as "735008.png"
item.get_icon("responses/icons", isrelative=True, filenameprop=bdomarket.ItemProp.ID)

# Save as "Blackstar Shuriken.png"
item.get_icon("responses/icons", isrelative=True, filenameprop=bdomarket.ItemProp.NAME)

print(item.to_dict())

Pig Cave Server Status

import asyncio
import bdomarket

async def main():
    pig = bdomarket.Pig(region=bdomarket.PigCave.EU)
    r = await pig.get_status()
    print(r.success, r.status_code)

asyncio.run(main())

Utility Functions

import datetime
import bdomarket

# Timestamp ↔ datetime conversion
dt = bdomarket.timestamp_to_datetime(1745193600.0)
ts = bdomarket.datetime_to_timestamp(datetime.datetime(2025, 4, 21, tzinfo=datetime.timezone.utc))

# Query an in-memory item list (e.g. result of item_database_dump_v2)
matches = bdomarket.get_items_by_name_from_db(item_list, "Blackstar Shuriken")
matches = bdomarket.get_items_by_id_from_db(item_list, 735008)

# Query a saved JSON file produced by item_database_dump_v2 → save_to_file
matches = bdomarket.search_items_by_name("responses/itemdump.json", "Kzarka")
matches = bdomarket.search_items_by_id("responses/itemdump.json", 12094)

💡 See example.py for a complete runnable demo of every feature, including all sync variants.

(back to top)

Roadmap

• Market Data Access
  • Retrieve real-time market data
  • Retrieve historical market data
  • Get waitlists, hotlists, item lists, sublists, and search results
• Boss Timers
  • Fetch world boss spawn times for all supported servers and regions
• Item Management
  • Query single or multiple items by ID
  • Dump large ranges of item data
  • Item object conversion to dictionary
  • Download item icons
• API Response Handling
  • Standardized ApiResponse object for all API calls
  • Deserialize responses into Python objects
• Data Export
  • Save API responses to JSON files
• Timestamp Conversion
  • Convert Unix timestamps to human-readable format
• Multi-Region and Multi-Language Support
  • Switch between BDO regions
  • Switch between supported languages
• Utilities
  • Print readable representations of items
  • Additional helper functions
• [/] Error Handling & Robustness
  • Graceful handling of network/API errors
  • Retry logic for failed requests
  • Safe terminal execution on Windows (Unicode safety)
• [/] Documentation
  • Comprehensive API documentation
  • Usage examples and tutorials
  • Docstrings for all public classes and methods
• Testing
  • Unit tests for core functionality
  • Integration tests for API endpoints
• Search & Filtering
  • Search items by name or partial match
  • Filter market data by category, price, etc.
• Performance Improvements
  • Async support for faster data retrieval
• CLI Tool
  • Command-line interface for quick queries and downloads
• Webhook/Notification Support
  • Notify users of market changes or boss

See the open issues for a full list of proposed features (and known issues).

(back to top)

Top contributors:

License

Distributed under the GNU General Public License v3.0.
See LICENSE for more information.

This project is copyleft: you may copy, distribute, and modify it under the terms of the GPL, but derivative works must also be open source under the same license.

Learn more about GPL-3.0 »

(back to top)

Contact

Szőke Dominik - [e-mail]

Project Link: https://github.com/Fizzor96/bdomarket

(back to top)