I was wondering if anyone here is aware of an API out there on the net anywhere that can receive a traditional character and send back the pinyin for it in JSON?

  • Out of curiosity: which approach or solution did you end up using?
    – Tsundoku
    Commented Jul 28, 2017 at 13:31
  • None yet, I am busy with other projects at the moment. This one is still in the idea stage :)
    – zeeple
    Commented Jul 28, 2017 at 15:49

6 Answers 6


There are several libraries for converting Chinese characters to pinyin. If you are comfortable with programming languages (which you probably are if you are asking for an API), your choice will depend on the programming languages you know, the quality of the library and the licence under which it is available. If you need a user interface, you should probably first look at pinyin4j and ZDT.

  • pinyin4net: C# library that supports both simplified and traditional Chinese characters. Output is hanyu pinyin. Licence: MIT.
  • PinYin4Objc: Objective-C library (with some Ruby) that supports both simplified and traditional Chinese characters and most popular pinyin systems. Licence: Apache License 2.0.
  • HanziPinyin: Swift library that supports both simplified and traditional Chinese characters. Licence: MIT License.
  • PiPinyin: Java library for Android for converting Chinese characters to pinyin. I assume it supports simplified characters but could not find out if it also supports traditional characters. (The older pinyin4android library, on which PiPinyin is based, appears to have no documentation.) Licence: Apache License 2.0.
  • pinyin4cpp: C++ library. Licence: Apache License 2.0. (Possibly inspired by pinyin4j, below.)
  • pinyin4j: Java library for conversion "between Chinese characters and most popular Pinyin systems". Can also ouput Wade-Giles, Yale and Gwoyeu Romatzyh! Licence: GPL v2.
  • Unihanconver: a Perl library "to convert between Traditional/Simplified Chinese directly in Unicode (not GB/Big5 conversion)". It can be used through a Gtk2+ Interface and from the console. (See also the developer site.) Licence: GPL 2.
  • ZDT (Zhongwen Development Tool), written in Java, "is an easy to use, open-source Mandarin Chinese flashcard application that can help you learn Chinese". One of its features is conversion between Chinese charactes and pinyin. (Developer site.) Licence: Eclipse Public License.
  • zh2tone / Chinese Word to ZuYin Code: a tool to convert Chinese characters/words to zhuyin fuhao (bopomofo). The tool has not been updated since 2012, has no licence, ...


  • I have not checked the quality of these libraries (alpha/beta/production-ready, test coverage, etc.) nor their completeness (how many characters they support etc.).
  • If you need such a library for professional use, I would steer clear of libraries that have no licence. Software available under Apache 2.0, MIT or BSD can be reused both in open source and commercial applications. Libraries available under a GPL licence ("GNU General Public Licence") can only be used in other GPL code.
  • 1
    I used pinyin4j in a production system and it gets the job done pretty well
    – blackgreen
    Commented Jan 18, 2017 at 20:37
  • @TXV I have checked it out and it seems to be char based only. How to handle tokens and text? Commented Apr 20, 2018 at 10:57
  • The OP asked for a pinyin API. Tokenization in Chinese is an entirely different beast, maybe you should open a separate thread.
    – blackgreen
    Commented Apr 21, 2018 at 14:32
  • 1
    @loretoparisi: apparently, for correctly handling segments you would need a segmenter such as github.com/huaban/jieba-analysis — I don't know the underlying approach, but have seen other libraries depending on it to do segmentation.
    – ccpizza
    Commented Mar 8, 2020 at 10:36

if you have programming knowledge, you may download the 國語辭典 (of taiwan), which is under creative commons 3.0


basically, it's 3 large excel files, using bash, grep, cut would give you relevant info of characters / words; and mandarin romanisation is one of them.

it's about 166000+ entries, that would be enough for "normal" usage.

have fun :)


Glosbe seems to offer this service:


{"result":"ok","text":"nǐ hǎo"}



In a very small experiment the service didn't seem so smart at distinguishing characters with multiple pronunciations:


{"result":"ok","text":"yín xíng"}

See the documentation at https://glosbe.com/a-api

Google Translate API might also offer what you're looking for (the console at http://translate.google.com does), but that service isn't free.

  • The Google Translate API does not seem to support pinyin. Commented Dec 25, 2017 at 13:53

It might be easier just to download CC-CEDICT in its entirety and look up your character in it. You can turn this into an API with very little effort.


I created a python module which converts a whole sentence into Pinyin. It also supports Cantonese/Jyutping. There's an accompanying REST API: https://github.com/lucwastiaux/python-pinyin-jyutping-sentence . It attempts to separate the sentence into words (which I haven't seen other chinese-to-pinyin modules do), using the jieba library.

Installing the module

pip install pinyin_jyutping_sentence

Mandarin / simplified characters

>>> import pinyin_jyutping_sentence
>>> pinyin_jyutping_sentence.pinyin("提高口语")
'tígāo kǒuyǔ'

Cantonese / traditional characters

>>> import pinyin_jyutping_sentence
>>> pinyin_jyutping_sentence.jyutping("我出去攞野食")
'ngǒ cēothêoi ló jěsik'

Calling the REST API


import requests
import json

url = "http://api.mandarincantonese.com/pinyin/办所有的事情"
response = requests.get(url)
>>> bàn suǒyǒu de shìqíng


# calling the API from python
import requests
import json

url = "http://api.mandarincantonese.com/jyutping/我哋盪失咗"
response = requests.get(url)
>>> ngǒ déi dongsāt zó

Why would you want to use an external API for static data that does not change over time?

The translation map is a constant, and all the libraries and services just wrap those maps.

As far as Chinese Traditional/Simplified to Pinyin goes there are a variety of free mappings available — here is one I've found to be the most complete and up-to-date which I 'ported' to javascript: https://github.com/glowinthedark/Simplified-and-Traditional-Chinese/blob/master/gb2312-big5/js/pinyin.js — this can be easily adapted to whatever programming language you need.

Or, as suggested in another answer, you can extract your own map from CEDICT.

Python-based identifier and conversion tool

Ruby-based conversion tool:

Other resources

The wechat app for android comes with built-in conversion tables for chinese2pinyin and traditional2simplified which you can peek at by renaming the apk file to zip, unzipping it, and then looking under the assets/fts folder where you will find fts_py.txt and fts_t2s.txt corrrespondingly. (Note that this might change in future versions.)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.