Table of Contents
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.
- 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
ApiResponseobject, 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.
If you like my project, you can buy me a coffee, many thanks ❤️ !
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.
Python installed on your system.
- Python >= 3.9
pip install bdomarketimport 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())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()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
UnofficialMarketmethods also have_syncvariants (e.g.get_list_queue_sync(),get_item_id_sync(),get_search_sync()).
import bdomarket
boss = bdomarket.Boss(server=bdomarket.Server.EU).scrape()
print(boss.get_timer()) # list of dicts
print(boss.get_timer_json()) # JSON stringimport 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())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())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.pyfor a complete runnable demo of every feature, including all sync variants.
- 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).
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.
Szőke Dominik - szokedominik@gmail.com
Project Link: https://github.com/Fizzor96/bdomarket