maplestory

easy-to-use MapleStory API wrapper for Rust

Regional Support

Currently, this crate is available on KMS and MSEA.
Other regions like GMS will be supported once Nexon provides official APIs 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.0.2" }
tokio = { version = "1.48.0", features = ["full"] }

Then, on your main.rs,

use maplestory::prelude::*;

#[tokio::main]
async fn main() {
    let api = MaplestoryApi::builder().region(Region::KMS).api_key("YOUR_API_KEY").build().unwrap();
    let ocid = api.get_id("00월").await.unwrap().ocid;
    let character_level = api
        .get_character_basic(&ocid, None)
        .await
        .unwrap()
        .character_level;

    println!("{character_level}");
}

This example prints 281, my character level (which has probably increased since I wrote this README).

MaplestoryApi

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

MaplestoryApi consists of 3 fields:

• region: Represents the region such as KMS, MSEA. Default is Region::KMS.
• api_key(required): 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 or MSEA 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.