maplestory

easy-to-use maplestory API wrapper for Rust

Regional Support

Currently, this crate is available on KMS, MSEA and TMS.
Other regions like GMS will be supported once NEXON provides official API for those regions.

Example

You can use other asynchronous crates, however, in this async example, we will use Tokio.

cargo add maplestory
cargo add tokio --features full

So your Cargo.toml would look like:

[dependencies]
maplestory = { version = "1.3.0" }
tokio = { version = "1.48.0", features = ["full"] }

Then, on your main.rs,

use maplestory::prelude::*;

async fn get_character_level() -> Result<i64, ApiError> {
    let api = MaplestoryApi::builder()
        .region(Region::KMS)
        // If api_key is not specified, it attempts to read the `MAPLESTORY_API_KEY` environment variable.
        .api_key("YOUR_API_KEY")
        .build();

    let ocid = api.get_id("00월").await?.ocid;

    // date is Option<&str> because it's optional parameter for API request.
    let character_level = api.get_character_basic(&ocid, Some("2025-10-20")).await?.character_level;

    Ok(character_level)
}

#[tokio::main]
async fn main() {
    match get_character_level().await {
        Ok(character_level) => println!("character level: {character_level}"),
        Err(e) => eprintln!("Error: {e}"),
    };
}

This example prints my character level, 281.

MaplestoryApi

struct MaplestoryApi {
    region: Region,
    api_key: String,
    origin: String,
}

MaplestoryApi consists of 3 fields:

• region: Represents the region(KMS/MSEA/TMS).
• api_key: Can be obtained from https://openapi.nexon.com/.
• origin: Default is "https://open.api.nexon.com". Or you can use any proxy server instead. For an example, visit nexon-open-api-proxy.

Schemas

For schema descriptions, please refer to KMS Docs, MSEA Docs or TMS Docs.
When the official documentation differs from the actual API response structure, schemas are based on the actual API responses.

Since API responses are in JSON format, their values are nullable.
However, making all Rust fields optional would be terrible.
So instead, through multiple attempts, only some fields are set as optional.

Due to this, errors may occur when actual response values, which are null, are received as non-optional values.
In such cases, please report them through Issues.

For example, the structure of the CharacterBasic schema is as follows:

struct CharacterBasic {
    date: Option<String>,
    character_name: String,
    world_name: String,
    character_gender: String,
    character_class: String,
    character_class_level: String,
    character_level: u32,
    character_exp: u64,
    character_exp_rate: String,
    character_guild_name: Option<String>,
    character_image: String,
    character_date_create: String,
    access_flag: String,
    liberation_quest_clear: String,
}

• When user does not provide optional date parameter, date field becomes null.
• When character not joined to a guild, character_guild_name field becomes null.
• Other fields are not null in any case.

API

Errors

License

This project is licensed under the MIT license.