Chinese Pinyin Conversion Data API

Plug Hanzi-to-pinyin conversion straight into your business systems.

Based on the Hanyu Pinyin scheme and a surname reading dictionary, it provides four endpoint types — Hanzi to pinyin, initials, sentence transliteration and name transliteration — handling polyphonic characters, neutral tones and special surname readings.

No need to maintain a pinyin dictionary or reading rules yourself.

View API Docs

Enterprise solution enquiryJSON APIBearer token authentication

Hanzi to pinyinPinyin initialsParagraph transliterationName to pinyin

Input text

1 Hanzi to pinyin Input characters

Text: Hanzi to pinyin
Type: Word

2 Pinyin initials Input characters

Text: Hanzi to pinyin
Type: Word

3 Paragraph transliteration Input text

Text: 你好，世界！
Type: Whole sentence

Conversion result

HÀN ZÌ
ZHUǍN PĪN YĪN

Conversion type: Hanzi to pinyin
Tone marks: With tones
Polyphonic characters: Processed
Separator style: Space separated
Characters submitted: 5
Output: hàn zì zhuǎn pīn yīn
Initials: h z z p y
Processing status: Done

4Core conversion endpoint

Polyphonic charactersContext-based decision

Surname readingSpecial readings included

REST APIJSON responses

There are open-source libraries for pinyin conversion, but "getting the name right" and "accurately transliterating whole sentences" are worlds apart.

The real question is not whether conversion is possible, but whether polyphonic characters, special surname readings and punctuation are handled properly.

Conversion difference sample Generic libraries vs purpose-built handling

001单 → dānCommon reading

002单 → shànSurname reading

003长 → cháng / zhǎngPolyphonic characters

Dedicated surname dictionary SHÀN Name-to-pinyin handled correctly

01
Polyphonic characters are hard to judge
Whether 长 reads cháng or zhǎng, and 行 reads xíng or háng, depends on context and the lexicon — generic libraries often get it wrong.
02
Special surname readings
单 as a surname reads shàn, 朴 reads piáo and 查 reads zhā — generic dictionaries often give the wrong reading.
03
Punctuation handling
Chinese punctuation ，。！？：“”‘’ must be replaced correctly with the corresponding English symbols; paragraph conversion easily misses or mis-converts them.
04
Self-built maintenance cost
Pinyin dictionaries, polyphonic character rules and surname reading tables need continuous maintenance and updates, consuming engineering resources.

From Hanzi to pinyin in six auditable conversion stages

A piece of text passes through tone marking, polyphonic character resolution, surname handling and punctuation transliteration to become an accurate pinyin result.

Collect

Based on the Hanyu Pinyin scheme and a surname reading dictionary

source.lemma()

Clean

Organises polyphonic character, neutral tone and variant reading rules

parse · dedupe

Normalize

Unifies tone marks and output formats

schema.map()

Reading matching

Resolves polyphonic characters from context and the lexicon

polyphone.resolve()

Surname handling

Maintains a separate special surname reading table

surname.lookup()

Deliver

Returns JSON results over a REST API

json_api.v1

You don't have to maintain a pinyin dictionary or reading rules.Call the API and get accurate results directly.

Four endpoints covering the core Hanzi-to-pinyin use cases

Unified REST API · JSON responses · Bearer token authentication. Hanzi-to-pinyin and name-to-pinyin are the product core, with initials and paragraph transliteration built on the same conversion engine.

Hanzi-to-pinyin API

Convert a string of Chinese characters into pinyin with tone marks

Enter a string of Chinese characters to get the pinyin for each with tone marks, space separated. Handles polyphonic characters automatically, choosing the right reading from context.

Pinyin with tones
Polyphonic character handling
Space separated
Character-by-character output

Text processing · search index · content annotation · data archiving

POST /v1/pinyin/convert

Static demo · Sample response200 OK

{
  "code": 0,
  "message": "success",
  "data": {
    "text": "汉字转拼音",
    "pinyin": "hàn zì zhuǎn pīn yīn",
    "pinyin_no_tone": "han zi zhuan pin yin",
    "initials": "hzzpy",
    "chars": [
      {"char": "汉", "pinyin": "hàn"},
      {"char": "字", "pinyin": "zì"},
      {"char": "转", "pinyin": "zhuǎn"},
      {"char": "拼", "pinyin": "pīn"},
      {"char": "音", "pinyin": "yīn"}
    ]
  }
}

Hanzi pinyin initials API

Get the string of pinyin initial characters for each Chinese character

Enter a string of Chinese characters and get the string of pinyin initials for each character — for search, abbreviations, codes and fast matching.

Initials concatenated
Optional separator
Case optional
Character-by-character output

Pinyin search · contact sorting · code abbreviations · fast matching

POST /v1/pinyin/initials

Static demo · Sample response200 OK

{
  "code": 0,
  "message": "success",
  "data": {
    "text": "汉字转拼音",
    "initials": "hzzpy",
    "initials_upper": "HZZPY",
    "initials_spaced": "h z z p y"
  }
}

Paragraph to pinyin API

Transliterate a whole Chinese paragraph into pinyin, keeping and converting punctuation

Converts a whole Chinese text into a pinyin string. Keeps Chinese punctuation ，。！？：“”‘’ and replaces it with the corresponding English symbols — ideal for sentence transliteration and reading annotations.

Sentence transliteration
Punctuation replacement
Polyphonic character handling
Keeps sentence breaks

Reading annotations · text transliteration · educational content · internationalisation

POST /v1/pinyin/translate

Static demo · Sample response200 OK

{
  "code": 0,
  "message": "success",
  "data": {
    "text": "你好，世界！",
    "pinyin": "nǐ hǎo, shì jiè!",
    "punctuation_map": {
      "，": ",",
      "。": ".",
      "！": "!",
      "？": "?",
      "：": ":"
    }
  }
}

Name to pinyin API

Name to pinyin, handling special surname readings correctly

Enter a Chinese personal name and get the pinyin. Some surname readings differ from the ordinary character reading — for example 单 normally reads dān but as a surname reads shàn. The endpoint maintains its own surname reading table to ensure accurate name transliteration.

Special surname readings
Given name transliterated by word
Case format
Separator optional

International shipping labels · passport applications · English system entry · contact management

POST /v1/pinyin/name

Static demo · Sample response200 OK

{
  "code": 0,
  "message": "success",
  "data": {
    "name": "单雄信",
    "surname": "单",
    "given_name": "雄信",
    "pinyin": "shàn xióng xìn",
    "pinyin_surname": "shàn",
    "surname_note": "As a surname, 单 reads shàn; the uncommon reading is dān",
    "passport_format": "SHAN XIONGXIN"
  }
}

These endpoints can enter your real business processes

Not another back office to open, but pinyin conversion where name entry, shipping labels, search and content processing actually happen.

Cross-border logistics and courier

Convert recipient and sender names to pinyin for international shipping labels and overseas warehouse system entry.

Chinese nameName to pinyin APILabel pinyin

SaaS / ERP systems

Automatically convert Chinese names to pinyin at registration for English systems and international communication.

User nameName to pinyin APIPinyin field

Search and contacts

Build a pinyin initials index so contacts and products can be searched quickly by pinyin abbreviation.

Chinese contentInitials APISearch index

Education products

Annotate Chinese content with pinyin for phonetic guides, reading and learning material generation.

Chinese textParagraph transliteration APIAnnotated content

Data processing and archiving

Bulk-convert Chinese text and names to pinyin for data standardisation and international archiving.

Batch textHanzi-to-pinyin APIPinyin datasets

Special surname readings are the core challenge of name-to-pinyin

Below are samples of common special surname readings, where generic pinyin libraries often give the wrong reading. The GooFuture name-to-pinyin API maintains its own surname reading table.

单 (surname): shàn
朴 (surname): piáo
查 (surname): zhā
区 (surname): ōu
繁 (surname): pó
Data status: Static demo

The name-to-pinyin API also handles

Compound surname transliteration (Ouyang, Sima)
Ethnic minority names
Passport-format output
Case control
Separator optional
Character readings

The value of an API is more than "returning pinyin to you"

GooFuture's core value comes before the conversion: getting polyphonic characters, surname readings and punctuation right so results can be used directly in business.

Reading

Polyphonic character handling

Resolves the correct reading of polyphonic characters from context and the lexicon.

Ambiguous → determined reading

Surname

Surname reading table

Special surname readings are maintained separately from ordinary character readings.

单 → shàn

Punctuation

Punctuation transliteration

Chinese punctuation ，。！？：“”‘’ replaced with the corresponding English symbols.

，→ ,

Format

Multiple output formats

Multiple outputs including with tones, without tones, initials and passport format.

Choose as needed

Deliver

API-first

No need to download and maintain dictionaries — call it on demand via API.

Query → JSON

From enquiry to your first API call in just three steps

Code and responses are static samples. Your consultant will propose an integration plan based on call volume, endpoint scope and delivery method.

01
Contact a consultant
Scan the QR code to add us on WeCom and tell us your business scenario, the endpoints you need and your expected call volume.
02
Confirm the plan
Confirm endpoint scope, call volume, output format and enterprise support needs.
03
Start integration
Get your API key and documentation, then wire the JSON results into your ERP, SaaS or business system.

cURLResponse

curl -X POST "https://api.goofuture.com/v1/pinyin/convert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"汉字转拼音"}'

Static demo · JSON response200 OK

{
  "code": 0,
  "data": {
    "pinyin": "hàn zì zhuǎn pīn yīn",
    "initials": "hzzpy"
  }
}

From testing to production

Choose a plan by call volume, endpoint scope and enterprise support. Your consultant quotes based on your business needs.

Basic

For API testing and product validation

Contact a consultant

Monthly requests: 1,000
Core endpoints: Hanzi to pinyin
Rate limits: Basic rate limiting
Output format: Standard format

Standard

For individual developers and small teams

Contact a consultant

Monthly requests: 50,000
Core endpoints: All four endpoints
Output format: All formats
Polyphonic characters: Support

Recommended plan

Professional

For SaaS products and business systems

Contact a consultant

Monthly requests: 500,000
Concurrency: Higher concurrency
Surname reading: Fully covered
Batch calls: Support

Enterprise

For platforms, data companies and large enterprises

Contact a consultant

Monthly requests: High-volume usage
Customisation: Output format / reading rules
Private deployment: Negotiable
Technical support: Enterprise technical support

The questions worth confirming before integrating a pinyin API

Straight answers on polyphonic characters, surname readings, punctuation handling and commercial integration.

There are open-source pinyin libraries — why do I still need this API?

If you only need to convert a few words occasionally, an open-source library will do. GooFuture is built for teams that need batch calls, system integration, special surname reading handling, punctuation transliteration and multiple output formats — centralising the maintenance of pinyin dictionaries, polyphonic character rules and surname reading tables, and delivering accurate results directly via API.

Do you support polyphonic characters?

Yes. The endpoint resolves polyphonic characters from context and the lexicon — for example 行 reads háng in 银行 (bank) and xíng in 行走 (to walk).

What is the difference between name-to-pinyin and ordinary Hanzi-to-pinyin?

The name-to-pinyin API maintains its own table of special surname readings. Some characters are read differently as a surname than as an ordinary character — for example 单 normally reads dān but reads shàn as a surname, and 朴 normally reads pǔ but reads piáo as a surname. The general Hanzi-to-pinyin endpoint does not distinguish surname contexts.

Does paragraph pinyin conversion keep punctuation?

Yes. The paragraph conversion endpoint keeps Chinese punctuation ，。！？：“”‘’ and replaces it with the corresponding English symbols, preserving the sentence breaks and tone of the original.

Which special surname readings are covered?

Common special surname readings include 单 (shàn), 朴 (piáo), 查 (zhā), 区 (ōu) and 繁 (pó). The surname reading table covers common polyphonic surnames; the exact scope can be confirmed during integration.

Do you support compound surnames?

Yes. The name-to-pinyin endpoint handles compound surnames such as 欧阳, 司马 and 上官, transliterating the surname and given name separately.

Do you support batch calls?

Yes. Professional plans and above support batch calls, for scenarios needing conversion of large volumes of text or names. Exact call volume and concurrency depend on the plan.

How do I integrate it into my own system?

The API can be used in internal systems and integrated into ERP, SaaS products, logistics systems, education platforms and data processing workflows; commercial usage is governed by the applicable plan and service agreement.

You no longer maintain your own pinyin dictionary and reading rules.

From resolving polyphonic characters and special surname readings to transliterating punctuation — we handle it all. Your systems just call the API.

Enterprise consultant onboarding · REST API · JSON responses

Chinese Pinyin Conversion Data API

Input text

Conversion result

Polyphonic characters are hard to judge

Special surname readings

Punctuation handling

Self-built maintenance cost

Collect

Clean

Normalize

Reading matching

Surname handling

Deliver

Hanzi-to-pinyin API

Hanzi pinyin initials API

Paragraph to pinyin API

Name to pinyin API

Cross-border logistics and courier

SaaS / ERP systems

Search and contacts

Education products

Data processing and archiving

The name-to-pinyin API also handles

Polyphonic character handling

Surname reading table

Punctuation transliteration

Multiple output formats

API-first

Contact a consultant

Confirm the plan

Start integration

You no longer maintain your own pinyin dictionary and reading rules.