MapleStory OpenAPI Python Client Library
A simple, but extensible Python implementation for the MapleStory OpenAPI.
Note
This library can only query data from the KMS(Korea MapleStory).
Overview
This library simplifies access to MapleStory's OpenAPI in Python, enabling queries of character, union, guild, and ranking information, as well as checks on Star Force, cubes, and potential abilities.
Installation
If you are using pip:
pip install maplestory
If you are using poetry:
poetry add maplestory
Supported Python Versions
Python 3.11 and 3.12 are fully supported and tested. While it may operate on subsequent versions of Python 3, testing against these newer versions is not currently conducted.
Unsupported Python Versions
- Python < 3.11
Third Party Libraries and Dependencies
The following libraries will be installed when you install the client library:
Usage
API credentials
To use the MapleStory OpenAPI, you first need to create a Nexon account at https://www.nexon.com. After creating your account, proceed to the NEXON OPEN API site and create a new application. Once your application is created, copy the API Key and set it as an environment variable or enter it into a .env
file within your project.
# set environment variable
MAPLESTORY_OPENAPI_KEY=INSERT_YOUR_KEY_HERE
Examples
Only the names, such as character names and guild names, are required.
If you wish to query a specific date in the past, you can also enter the date. By default, the query is based on the date of yesterday. (The plan is to detail this further by API type in the future.)
Character
You can query all character data using just the character name using Character
class.
>>> from mapletory.services.character import Character
>>> char = Character(name="์จ์ค์จ")
>>> print(char)
CharacterBasic(
date=datetime.datetime(2024, 2, 10, 0, 0, tzinfo=TzInfo(+09:00)),
name='์จ์ค์จ',
world='์ค์นด๋์',
gender='์ฌ',
job='์ํฌ๋ฉ์ด์ง(์ฌ,์ฝ)',
job_level=6,
level=280,
exp=29014907373569,
exp_rate=86.232,
guild_name='์จ์ค์จ',
image=<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=96x96 at 0x1063C16D0>
)
>>> print(char.ability)
Ability(
date=datetime.datetime(2024, 2, 4, 0, 0, tzinfo=TzInfo(+09:00)),
grade='๋ ์ ๋๋ฆฌ',
info=[
AbilityInfoItem(grade='๋ ์ ๋๋ฆฌ', value='๋ฒํ ์คํฌ์ ์ง์ ์๊ฐ 50% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ ๋ํฌ', value='์ํ ์ด์์ ๊ฑธ๋ฆฐ ๋์ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 8% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ ๋ํฌ', value='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 10% ์ฆ๊ฐ')
],
remain_fame=465283,
preset_no=1,
preset1=AbilityPreset(
grade='๋ ์ ๋๋ฆฌ',
info=[
AbilityInfoItem(grade='๋ ์ ๋๋ฆฌ', value='๋ฒํ ์คํฌ์ ์ง์ ์๊ฐ 50% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ ๋ํฌ', value='์ํ ์ด์์ ๊ฑธ๋ฆฐ ๋์ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 8% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ ๋ํฌ', value='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 10% ์ฆ๊ฐ')
]
),
preset2=AbilityPreset(
grade='๋ ์ ๋๋ฆฌ',
info=[
AbilityInfoItem(grade='๋ ์ ๋๋ฆฌ', value='์์ดํ
๋๋กญ๋ฅ 19% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ํฝ', value='๋ฒํ ์คํฌ์ ์ง์ ์๊ฐ 19% ์ฆ๊ฐ'),
AbilityInfoItem(grade='์ ๋ํฌ', value='๋ฉ์ ํ๋๋ 15% ์ฆ๊ฐ')
]
),
preset3=AbilityPreset(
grade='์ํฝ',
info=[
AbilityInfoItem(grade='์ํฝ', value='๋ชจ๋ ๋ฅ๋ ฅ์น 15 ์ฆ๊ฐ'),
AbilityInfoItem(grade='๋ ์ด', value='๋ชจ๋ ๋ฅ๋ ฅ์น 5 ์ฆ๊ฐ'),
AbilityInfoItem(grade='๋ ์ด', value='๋ชจ๋ ๋ฅ๋ ฅ์น 5 ์ฆ๊ฐ')
]
)
)
Gulid
To query guild information, you only need the guild name and the world name to which the guild belongs.
>>> from mapletory.services.guild import Guild
>>> guild = Guild(name="๋ฆฌ๋", world="์ค์นด๋์")
>>> print(guild)
Guild(
name='๋ฆฌ๋',
world='์ค์นด๋์',
id='789b457f357ce6ac3e1bfa1c95ccaac6',
basic=GuildBasic(
date=datetime.datetime(2024, 2, 7, 0, 0, tzinfo=TzInfo(+09:00)),
world='์ค์นด๋์',
name='๋ฆฌ๋',
level=29,
fame=65312548,
point=10000000,
master_name='์๋ธ',
member_count=160,
members=[
'์๋ธ',
'์ถฉ์ ์ ๋ญ์ด1',
'์ถฉ์ ์ ๋ญ์ด2',
...
],
skills=[
GuildSkill(
name='์ฅ์ฌ๊พผ',
description='[๋ง์คํฐ ๋ ๋ฒจ : 3]\r\n์์ ์์ ๋ฌผ๊ฑด์ ๊ตฌ๋งค ์ ์ธ๊ฒ ์ด ์ ์๋ค. ๋จ, ์ผ๋ถ ์์ดํ
์๋ ์ ์ฉ๋์ง ์๋๋ค.\n[ํ์ ์กฐ๊ฑด]: ๊ธธ๋ 10๋ ๋ฒจ ์ด์\n[ํ์ ์คํฌ]: ์๋์ด ๋์ ๋๋ค 3๋ ๋ฒจ ์ด์',
level=3,
effect='์์ ์์ ๋ฌผ๊ฑด ๊ตฌ๋งค ์ 4% ์ธ๊ฒ ๊ตฌ๋งค ๊ฐ๋ฅ. ๋จ, ํ๋งค ๊ฐ๊ฒฉ ๋๋น ๊ตฌ๋งค ๊ฐ๊ฒฉ์ด 70% ์ด์์ผ ๊ฒฝ์ฐ ์ ์ฉ๋์ง ์์',
icon=Url('https://open.api.nexon.com/static/maplestory/SkillIcon/KFGDLHOBMI.png')
),
...
],
noblesse_skills=[
GuildSkill(
name='๋ณด์ค ํฌ๋ง ๋จธ์ ',
description='[๋ง์คํฐ ๋ ๋ฒจ : 15]\r\n์ผ์ ์๊ฐ ๋์ ๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง๊ฐ ์ฆ๊ฐํ๋ค.',
level=15,
effect='30๋ถ ๋์ ๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 30% ์ฆ๊ฐ, ์ฌ์ฌ์ฉ ๋๊ธฐ์๊ฐ 60๋ถ',
icon=Url('https://open.api.nexon.com/static/maplestory/SkillIcon/KFGDLHPBOC.png')
),
...
],
mark=<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=17x17 at 0x10C9C04D0>,
is_custom_mark=True
)
)
Union
Raider effects, occupation effects, and artifact effects each show a summarized result.
For example, if there are two instances of STR 100 increase
, it will be shown as STR 200 increase
.
In addition, STR, DEX, LUK 40 increase
is broken down into STR 40 increase
, DEX 40 increase
, LUK 40 increase
, and Attack/Magic Attack 20 increase
is calculated as Attack 20 increase
, Magic Attack 20 increase
.
However, options that ignore defense rate are not combined due to multiplicative application. (Plans are to provide ignored defense rate calculations in a multiplicative manner in the future.)
>>> from maplestory.services.union import Union
>>> union = Union(character_name="์จ์ค์จ")
>>> print(union)
Union(
character_name='์จ์ค์จ',
date=datetime.datetime(2024, 2, 9, 9, 59, 37, 37959, tzinfo=zoneinfo.ZoneInfo(key='Asia/Seoul')),
level=8870,
grade='๊ทธ๋๋ ๋ง์คํฐ ์ ๋์จ 2',
raider_stats=UnionStats(
[
UnionStat(stat='DEX 320 ์ฆ๊ฐ'),
UnionStat(stat='INT 660 ์ฆ๊ฐ'),
UnionStat(stat='LUK 440 ์ฆ๊ฐ'),
UnionStat(stat='STR 440 ์ฆ๊ฐ'),
UnionStat(stat='๊ฒฝํ์น ํ๋๋ 10% ์ฆ๊ฐ'),
UnionStat(stat='๊ณต๊ฒฉ ์ 20%์ ํ๋ฅ ๋ก ๋ฐ๋ฏธ์ง 16% ์ฆ๊ฐ'),
UnionStat(stat='๊ณต๊ฒฉ๋ ฅ 20 ์ฆ๊ฐ'),
UnionStat(stat='๋ง๋ ฅ 20 ์ฆ๊ฐ'),
UnionStat(stat='๋ฉ์ ํ๋๋ 4% ์ฆ๊ฐ'),
UnionStat(stat='๋ฐฉ์ด์จ ๋ฌด์ 5% ์ฆ๊ฐ'),
UnionStat(stat='๋ฒํ ์ง์์๊ฐ 20% ์ฆ๊ฐ'),
UnionStat(stat='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 5% ์ฆ๊ฐ'),
UnionStat(stat='์ํ ์ด์ ๋ด์ฑ 4 ์ฆ๊ฐ'),
UnionStat(stat='์คํฌ ์ฌ์ฌ์ฉ ๋๊ธฐ์๊ฐ 5% ๊ฐ์'),
UnionStat(stat='์ ๊ณต๊ฒฉ๋ง๋ค 70%์ ํ๋ฅ ๋ก ์์ MP์ 8% ํ๋ณต'),
UnionStat(stat='์ต๋ MP 6% ์ฆ๊ฐ'),
UnionStat(stat='ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 5% ์ฆ๊ฐ'),
UnionStat(stat='ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 8% ์ฆ๊ฐ')
]
),
occupied_stats=UnionStats(
[
UnionStat(stat='INT 25 ์ฆ๊ฐ'),
UnionStat(stat='LUK 5 ์ฆ๊ฐ'),
UnionStat(stat='๋ง๋ ฅ 5 ์ฆ๊ฐ'),
UnionStat(stat='๋ฐฉ์ด์จ ๋ฌด์ 33% ์ฆ๊ฐ'),
UnionStat(stat='๋ฒํ ์ง์์๊ฐ 40% ์ฆ๊ฐ'),
UnionStat(stat='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 23% ์ฆ๊ฐ'),
UnionStat(stat='ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 20.00% ์ฆ๊ฐ'),
UnionStat(stat='ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 11% ์ฆ๊ฐ')
]
),
artifact_effects=[
UnionArtifactEffect(name='์ฌ์คํฏ 150 ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๊ณต๊ฒฉ๋ ฅ 18, ๋ง๋ ฅ 18 ์ฆ๊ฐ', level=6),
UnionArtifactEffect(name='๋ฐ๋ฏธ์ง 15.00% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 15.00% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ชฌ์คํฐ ๋ฐฉ์ด์จ ๋ฌด์ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ฒํ ์ง์์๊ฐ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='์์ดํ
๋๋กญ๋ฅ 7% ์ฆ๊ฐ', level=6),
UnionArtifactEffect(name='ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 2.40% ์ฆ๊ฐ', level=6)
]
)
You can also access attributes in Korean.
๊ณต๊ฒฉ๋์ํจ๊ณผ
๊ณต๊ฒฉ๋์ ๋ นํจ๊ณผ
์ํฐํฉํธํจ๊ณผ
>>> print(union.๊ณต๊ฒฉ๋์ํจ๊ณผ)
UnionStats(
[
UnionStat('DEX 320 ์ฆ๊ฐ'),
UnionStat('INT 660 ์ฆ๊ฐ'),
UnionStat('LUK 440 ์ฆ๊ฐ'),
UnionStat('STR 440 ์ฆ๊ฐ'),
UnionStat('๊ฒฝํ์น ํ๋๋ 10% ์ฆ๊ฐ'),
UnionStat('๊ณต๊ฒฉ ์ 20%์ ํ๋ฅ ๋ก ๋ฐ๋ฏธ์ง 16% ์ฆ๊ฐ'),
UnionStat('๊ณต๊ฒฉ๋ ฅ 20 ์ฆ๊ฐ'),
UnionStat('๋ง๋ ฅ 20 ์ฆ๊ฐ'),
UnionStat('๋ฉ์ ํ๋๋ 4% ์ฆ๊ฐ'),
UnionStat('๋ฐฉ์ด์จ ๋ฌด์ 5% ์ฆ๊ฐ'),
UnionStat('๋ฒํ ์ง์์๊ฐ 20% ์ฆ๊ฐ'),
UnionStat('๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 5% ์ฆ๊ฐ'),
UnionStat('์ํ ์ด์ ๋ด์ฑ 4 ์ฆ๊ฐ'),
UnionStat('์คํฌ ์ฌ์ฌ์ฉ ๋๊ธฐ์๊ฐ 5% ๊ฐ์'),
UnionStat('์ ๊ณต๊ฒฉ๋ง๋ค 70%์ ํ๋ฅ ๋ก ์์ MP์ 8% ํ๋ณต'),
UnionStat('์ต๋ MP 6% ์ฆ๊ฐ'),
UnionStat('ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 5% ์ฆ๊ฐ'),
UnionStat('ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 8% ์ฆ๊ฐ')
]
)
>>> print(union.๊ณต๊ฒฉ๋์ ๋ นํจ๊ณผ)
UnionStats(
[
UnionStat('INT 25 ์ฆ๊ฐ'),
UnionStat('LUK 5 ์ฆ๊ฐ'),
UnionStat('๋ง๋ ฅ 5 ์ฆ๊ฐ'),
UnionStat('๋ฐฉ์ด์จ ๋ฌด์ 33% ์ฆ๊ฐ'),
UnionStat('๋ฒํ ์ง์์๊ฐ 40% ์ฆ๊ฐ'),
UnionStat('๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 23% ์ฆ๊ฐ'),
UnionStat('ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 20.00% ์ฆ๊ฐ'),
UnionStat('ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 11% ์ฆ๊ฐ')
]
)
>>> print(union.์ํฐํฉํธํจ๊ณผ)
[
UnionArtifactEffect(name='์ฌ์คํฏ 150 ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๊ณต๊ฒฉ๋ ฅ 18, ๋ง๋ ฅ 18 ์ฆ๊ฐ', level=6),
UnionArtifactEffect(name='๋ฐ๋ฏธ์ง 15.00% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ณด์ค ๋ชฌ์คํฐ ๊ณต๊ฒฉ ์ ๋ฐ๋ฏธ์ง 15.00% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ชฌ์คํฐ ๋ฐฉ์ด์จ ๋ฌด์ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='๋ฒํ ์ง์์๊ฐ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='์์ดํ
๋๋กญ๋ฅ 7% ์ฆ๊ฐ', level=6),
UnionArtifactEffect(name='ํฌ๋ฆฌํฐ์ปฌ ํ๋ฅ 20% ์ฆ๊ฐ', level=10),
UnionArtifactEffect(name='ํฌ๋ฆฌํฐ์ปฌ ๋ฐ๋ฏธ์ง 2.40% ์ฆ๊ฐ', level=6)
]