README.md

MapleStory OpenAPI Python Library

This Python library enables the use of the MapleStory OpenAPI of Nexon.

Packages written in other languages can be found HERE.

English | 한국어

Notice

💡 Notice 1: Migration is required when updating to version 3.5.0. Please refer to the documentation for Migration.

🌏 Notice 2: Starting from version 3.4.0, support for tms region has been added. You can now retrieve data from KMS, TMS, MSEA.

🌏 Notice 3: Starting from version 3.0.0, support for msea region has been added.

💡 Notice 4: Migration is required when updating from version 2.x.x to 3.0.0. Please refer to the documentation for Migration.

Installation

Install the latest version of the Python library in your python project:

pip install maplestory-openapi

Usage

API Key

Before using the library, register your application and obtain an api key from the Nexon Open API Console.

Applications must be registered separately for each region. (For example, an API key issued for KMS cannot be used to request data from MSEA.)

Region

Currently, this library supports data retrieval from the KMS, TMS, MSEA regions. To access data from a specific region, import the corresponding package path.

from maplestory_openapi.kms import MapleStoryApi # data from KMS
# or
from maplestory_openapi.msea import MapleStoryApi # data from MSEA

Even though the regions differ, each package inherits the same interface, ensuring a consistent API usage experience across all regions.

Sample Code

Below is an example that retrieves the identifier of a specific character from the KMS server based on the nickname, and then fetches that character’s basic information.

from maplestory_openapi.kms import MapleStoryApi
from maplestory_openapi.common import MapleStoryApiException

api_key = '{Your API Key}'
api = MapleStoryApi(api_key=api_key)

# run your code
try:
    character = api.get_character_id('{Your Character Name}')
    character_basic = api.get_character_basic(ocid=character.ocid)

    print(character_basic)
# exception handling
except MapleStoryApiException as e:
    # handle MapleStoryApiException

You can find more examples in the test cases at the following link.

• Character Information Retrieval
• Union Information Retrieval
• Guild Information Retrieval
• Battle Practice Information Retrieval
• History Information Retrieval
• Scheduler Information Retrieval
• Ranking Information Retrieval
• Notice Information Retrieval

Features

This library supports all apis published in the MapleStory OpenAPI official docs.

Some features are supported only in specific regions. Please refer to the official documentation for each region for details.

• KMS: https://openapi.nexon.com/game/maplestory
• KMS(for Nexon Friends Exclusive APIs): https://openapi.nexon.com/ko/friends/maplestory
• TMS: https://openapi.nexon.com/game/maplestorytw
• MSEA: https://openapi.nexon.com/game/maplestorysea

Exception Handling

Handle MapleStoryApiException to safely make calls, ensuring that specific Status defined in the MapleStory OpenAPI Guide are not encountered.

While MapleStoryApi is designed to prevent the occurrence of certain Status, exceptions may arise due to developer mistakes.

Therefore, it's recommended to use MapleStoryApiException for exception handling based on the error code list described in the table below.

ErrorCode	Description
OPENAPI00001	Internal server error
OPENAPI00002	Access denied
OPENAPI00003	Invalid identifier
OPENAPI00004	Request format error (incorrect parameter input)
OPENAPI00005	Invalid api key
OPENAPI00006	Invalid api path
OPENAPI00007	Request allowance (Rate Limit) exceeded
OPENAPI00009	Not prepared data
OPENAPI00010	Game server maintenance
OPENAPI00011	API server maintenance