By using this Neople’s site, you agree to our use of cookies. Click here for more information

Basic Guide

  • Home > API Guide > Basic Guide

Common Guide


Open API is a REST API service provided to external developers to easily access various information within the game.
Open API offers resources (APIs) that developers can utilize, and the range of data it provides is continuously reviewed and increased.

Common Guide Overview

The Common Guide explains the information that developers need to know in advance when developing applications using the Open API.

The content of this document is subject to change depending on the situation.

Common Guide Table of Contents





Getting Started with Open API


To use the Open API, you need to sign up as a member and register your application.
Upon registering the application, an API Key will be issued, which you can use to access the Open API service.
When making API calls, make sure to include the API Key in the HTTP header or request parameters.

Take care to not expose your API Key to prevent unauthorized usage, as there are request limits for API calls.


Applications

After signing up for Neople Developers, you can view the list on the My Page.

Application Registration

Click the registration button in the My Page > Application List to go to the application registration page.
Enter the application name , description , and other details, then click the registration button to complete the application registration process and receive an API Key.

Check Application

Click the settings button in the My Page > Application List to navigate to the detailed information page of the application.
On the application details page, you can view the application information, API Key, and API call history.

Deleting an Application

On the application details page, clicking the Delete Application button will delete the application information, including the API Key and API call history.

Reissue API Key

Clicking the Reissue API Key button on the application details page will reissue the API Key.
The previous API Key will no longer be valid after being reissued.



API Configuration


API Invocation

Example of Direct URL Invocation

https://api.dfoneople.com/df/{server name}/{reference}?apikey={APIKey}&characterName={value}

Example of CURL Invocation

curl --request GET 'https://api.dfoneople.com/df/{server name}/{reference}?apikey={APIKey}&characterName={value}' --include

Example of Sending API Key in the Request Header

API Key issued from Request Header can also be input for use.

curl -i -XGET -H 'apikey:<APIKey>' https://api.dfoneople.comdf/{server name}/{reference}?characterName={value}'


API Limitations

There are limitations on the number of invocations allowed when using the API.

The allowance upon application registration is 500 invocations per second.

Maximum Allowance per Second Maximum Allowance per Minute Maximum Allowance per Hour
500 30,000 1,800,000


URL Encoding

For some requests in the Open API, search values need to be URL-encoded.
You can check which variables require URL encoding in the API Documentation.
For these variables, it is recommended to use encoding formats like javascript encodeURIComponent, as it allows sending special characters.
(Please note that encodeURI does not encode some special characters, so it may not produce the desired results.)

Sample codes may differ depending on the version for each language.

Node.js Encoding Sample

const qs = require('querystring');
let itemName = 'Clear Cube Fragement';
let url = `https://api.dfoneople.com/df/items?&apikey=<APIKey>&itemName=${qs.escape(itemName)}`;

PHP Encoding Sample

$encText = rawurlencode("Open API");

$url = "https://api.dfoneople.com/df/items?itemName=".$encText;

JAVA Encoding Sample

private String getUrl(itemName){
    String url = "https://api.dfoneople.com/df/items?itemName=" + encodeURIComponent(itemName);
}

public static String encodeURIComponent(String component)   {     
    String result = null;      

    try {       
        result = URLEncoder.encode(component, "UTF-8") ;     
    catch (UnsupportedEncodingException e) {       
        result = component;     
    }      

    return result;   
}



View Statistics

Click the Settings button on the My Page > Application List to navigate to the Application Details screen.
On the Application Details screen, you can check the API invocation history for the past week.





Glossary of API Terms



API Basics

API (Application Programming Interface)

API (Application Programming Interface) refers to various interfaces that allow developers to write applications through programming tasks for operating systems, systems, applications, libraries, etc. (e.g., Window API, Java API, HTML5 API, Android API...).

Open API

Open API refers to APIs that are opened (made accessible) to allow external usage of game content by invoking them through the web protocol (HTTP). Most of the APIs provided by Neople Developers, such as character and auction information, are accessible via Open APIs that can be invoked using URL and HTTP.


API Authentication

API Gateway

Most Open APIs are accessed through the server https://api.dfoneople.com. This server acts as the API gateway server, which verifies the correctness of API invocations, checks if the user is authenticated, and verifies if the API invocation is within the allowed limits. If the invocation is incorrect, it returns an error code and message.

API Key

To use Open APIs, you need to obtain a unique text string called an 'API Key' for each API. By sending the API Key along with the API invocation to the API gateway server, it authenticates the user.


API Request

Request URL

The web address (URL) of the API used to make an Open API invocation. Currently, the URL structure for invoking APIs is in the form of https://api.dfoneople.com/df/API.

Request Parameter

These are the values that need to be sent to the server when making an Open API invocation. Make sure to refer to each API specification for the correct request parameter names and ensure that all required request parameters are included.

URL Encoding

When special characters are included in the value of a request parameter, they may get corrupted during server transmission. To prevent this, the values should be converted into code values according to the specified rules and transmitted. This process is called URL encoding. The reverse process of converting the URL-encoded value back to its original form is called URL decoding.


HTTP Terminology

Method

In the HTTP protocol, web servers and clients use predefined methods for sending and receiving request data. The W3C defines eight methods, including GET and POST.
In the case of Open API, only the GET method is supported, and API calls must be made using the GET method.

HTTP Headers

HTTP headers contain metadata that describes the request and request data sent to the web server (such as the method, request URL, HTTP protocol version, etc.). Additionally, HTTP headers can be used to send additional names and values. Open API typically includes the API Key in the HTTP headers for authentication.

HTTP Status Codes

When making an API call, the server responds with an HTTP status code along with the response content. If the call is successful, the HTTP status code is 200. If the method used for the call is incorrect, the server returns status codes such as 400, 401, 404, 500, 503, indicating various types of errors. For more detailed information, please refer to the HTTP status codes.





DFO Game Information




DFO Item Rarity

This section describes rarity information for DFO items.

Rarity Color Code
Common #FFFFFF
Uncommon #68D5ED
Rare #B36BFF
Unique #FF00FF
Epic #FFB400
Chronicle #FF6666
Legendary #FF7800
Mythic -



DFO Column Information

This sections describes DFO’s Column information codes.

API Column Name Description
Character characterId Character Unique Code
Character characterName Character Name
Character jobId Character Unique Class Code
Character jobName Character Class Name
Character jobGrowId Character Awakening Class Unique Code
Character jobGrowName Character Awakening Class Name
Character adventureName Explorer Club Name
Character fame Character Adventurer Fame
Character guildId Guild Unique Code
Character guildName Guild Name
Item itemId Item Unique Code
Item itemName Item Name
Item itemRarity Item Rarity Grade
Item itemTypeId Item Type Unique Code
Item itemType Item Type
Item itemTypeDetailId Item Subtype Unique Code
Item itemTypeDetail Item Subtype
Item itemAbility Item Fixed Stats
Item itemAvailableLevel Item Equippable Level
Item optionAbility Item Additional or Selectable Stats
Item setItemId Set Item Unique Code
Item setItemName Set Item Name
Item setItemOption Set Item Option Information
Item setItemInfo Set Item Composition Information
Item fullsetExplain Explanation of Additional Options for Full Set Item
Item slotColor Item Slot Unique Color
Item slotNo Item Slot Unique Number
Item slotId Item Slot Unique Code
Item slotName Item Slot Name
Item itemStatus Equipment Item Numeric Information
Item obtainInfo Item Acquisition Information (Dungeon/Shop)
Item itemExplain Explanation of Additional Options for Item
Item itemExplainDetail Details of Additional Options for Item
Item itemFlavorText Item Background Story Description
Item itemReinforceSkill Equipment Item Skill Enhancement Information
Item itemGradeName Item Grade Name
Item itemGradeValue Item Grade Value (1 to 100%)
Item cardInfo Card Information
Item enchant Card Upgrade Value Information
Item itemBuff Exclusive Options for Crusader and Enchantress
Item talismanInfo Talisman Item Information
Item runeInfo Rune Item Information
Item transformOptionInfo Conversion Option Information
Item transformOptionInfo.active Option Conversion Availability
Item remodelInfo Modification Option Information
Item remodelInfo.stepInfo Modification Option Information per Stage
Item remodelInfo.stepInfo.transformOption Conversion Option Availability within Modification Option Information per Stage
Item mythologyInfo Mythic Item Option Information
Item sirocoInfo Sirocco Fusion Item Option Information
Item aeternaInfo Aeterna Fusion Item Option Information
Item ozmaInfo Ozma Fusion Item Option Information
Item fixedOption Fixed option information
Item customOption Custom option information
Item asrahanOption God of Mist Weapon Starfield of Memories Option Information
Item transfer Transfer Availability for Growth Options and Specific Options
Item expRate Growth EXP Information
Item damage Damage Value
Item buff Buff Power
Item hashtag Hashtags
Item exaltedInfo Exalted Equipment Option Information
Equipped Item refine Item Refinement Value
Equipped Item reinforce Item Reinforcement or Amplification Value
Equipped Item amplificationName Item Amplification Stat Value
Equipped Item enchant Enchantment (Bead)
Equipped Item darkRevelation Black Sky’s Power Activation for Weapons
Equipped Item skin Weapon Skins
Equipped Item upgradeInfo Sirocco Essence/Fusion Material Item Information
Equipped Item engraveName Otherworldy Name Engraving Information
Equipped Item mistGear Mist Gear information
Equipped Item refinedMistGear Refined Mist Gear information
Equipped Item pureMistGear Pure Mist Gear information
Equipped Item tune Equipment Tuning Information
Equipped Item setPoint Item Set Point Value
Equipped Item fusionStone Fusion Stone Equip Status
Equipped Item potency Exalted Equipment Potency Information
Avatar cloneAvatarName Clone Avatar Item Name
Creature cooldownTime Skill Cooldown
Creature clone Creature Skins
Creature description Additional Information
Skill skillId Skill Unique Code
Skill requiredLevel Minimum Acquisition Level
Skill requiredLevelRange Acquisition Level Range
Skill costType Skill Point Type (SP/TP)
Skill desc Skill Description
Skill descDetail Detailed Skill Description
Skill descSpecial Explanation of Special Skill Functions
Skill consumeItem Items Consumed for Skill Usage
Skill maxLevel Maximum Level
Skill preRequiredSkill Preceding Skills
Skill consumeMp MP Consumption Amount
Skill coolTime Cooldown Time
Skill castingTime Casting Time
Skill levelInfo Detailed Skill Option Information
Skill hash Skill Tree Share Code



DFO Item wordType

The wordType (search type) is a request variable used in API search functions (items/setitems), and it is currently composed of match/front/full..
※ It is recommended to use "match" for wordType, but it may change depending on the situation.

match

Retrieves information that matches the search value

Request : /df/items?itemName=Blue Beryl Armor&wordType=match
Result : Retrieves item information that matches the itemName"Blue Beryl Armor" ("itemName":"Blue Beryl Armor")

front

Retrieves information where the search value matches the beginning of the word.

Request : /df/items?itemName=Blue&wordType=front
Result : Retrieves item information where the itemNamestarts with "Blue" ("itemName":"Blue Beryl Armor", "itemName":"Blue Beryl Belt", "itemName":"Blue....", ...)

full

Retrieves information that includes the search value.
Items can be searched for by individual word units separated by spaces. However, a complete word must be entered for the search to be possible.

Request : /df/items?itemName=Blue&wordType=full
Result : Retrieves item information where the itemNamecontains the word "Blue" ("itemName":"Blue Beryl Armor", "itemName":"Blue Beryl Protectors", ...)





DFO character wordType

The wordType (search type) is a request variable used in API search functions (character), and it is currently composed of match/full..

match

Retrieves information that matches the search value

Request :Request : /df/servers/cain/characters?characterName=Slayer&wordType=match
Result : Retrieves character information that matches the characterName "Slayer" ("characterName":"Slayer")

full

Retrieves information that includes the search value.
Minimum 4 to a maximum of 12 letters can be used.

Request : /df/servers/cain/characters?characterName=Slayer&wordType=full
Result : Retrieves character information where the characterName contains the word "Slayer" ("characterName":"KdkSlayerMan", "characterName":"SlayerSlayerHae", ...)






DFO Time Converter

DFO’s server use’s UTC as the standard time.

However, you can use this feature to convert

the UTC time to your local time.

This will allow you to keep track of important things

such as start/end of events, expiration of

event/sale items, etc. in your local time.

This setting will only be applied to the current

browser you are accessing from.

Server Time

06 : 21

Tue, 15 Jul 2025 (UTC)

Local Time