WPS Partnership API V2

Update Time	Notes
Dec 13, 15:00	Added xclozeType and xchunkType descriptions for the tip endpoint
Dec 18, 17:00	Updated error category localization and suggestions
Dec 25, 14:00	Added combined endpoint; errors now support one-to-many `cands`
Dec 25, 16:00	Added `xconfusion` description in tip

1. Overview

Authentication

IP whitelist is used for authentication.

shell

curl --request POST \
  --url https://url_cn/api \
  -H "Content-Type: application/json" \
  --data '{"json":"data"}'

curl --request POST \
  --url https://url_cn/api \
  -H "Content-Type: application/json" \
  --data '{"json":"data"}'

Conventions

IP whitelist authentication
Submit JSON data in the request body
Responses are also in JSON format

Flow

Split article into sentences
After splitting, errors, warnings, and tips can be fetched in parallel

Environments

url_cn entry points:

Domain	Type	Description
http://wps.pigai.org:8756	string	Production environment

2. Sentence Splitting Endpoint

Endpoint: POST https://url_cn/wpsv2-xtext

Request:

json

{
    "text": "She has ready.\nI pay attention to the box. This are gramamtical sentence."
}

{
    "text": "She has ready.\nI pay attention to the box. This are gramamtical sentence."
}

Field	Type	Required	Description
text	string	Yes	Input text

Response:

json

{
    "snts": [
        "She has ready.",
        "\nI pay attention to the box.",
        "This are gramamtical sentence."
    ],
    "offsets": [0, 14, 43]
}

{
    "snts": [
        "She has ready.",
        "\nI pay attention to the box.",
        "This are gramamtical sentence."
    ],
    "offsets": [0, 14, 43]
}

Field	Type	Required	Description
snts	string[]	Yes	Sentences after splitting
offsets	number[]	No	Character offsets of each sentence

3. Error Endpoint

Endpoint: POST https://url_cn/wpsv2-err

Request:

json

{
    "snts": [
        "She has ready.\n",
        "I pay attention to the box.",
        "This are gramamtical sentence."
    ]
}

{
    "snts": [
        "She has ready.\n",
        "I pay attention to the box.",
        "This are gramamtical sentence."
    ]
}

Field	Type	Required	Description
snts	string[]	Yes	Sentences after splitting

Response:

json

{
    "data": [
        {
            "snt": "She has ready.\n",
            "edits": [
                {
                    "offset": 4,
                    "itok": 1,
                    "orig": "has",
                    "corr": "is",
                    "type": "R",
                    "cate": "VERB"
                }
            ],
            "toks": [
                { "i": 0, "offset": 0, "textws": "She " },
                { "i": 1, "offset": 4, "textws": "has " },
                { "i": 2, "offset": 8, "textws": "ready" },
                { "i": 3, "offset": 13, "textws": "." },
                { "i": 4, "offset": 14, "textws": "\n" }
            ]
        },
        {}
    ],
    "total": 4
}

{
    "data": [
        {
            "snt": "She has ready.\n",
            "edits": [
                {
                    "offset": 4,
                    "itok": 1,
                    "orig": "has",
                    "corr": "is",
                    "type": "R",
                    "cate": "VERB"
                }
            ],
            "toks": [
                { "i": 0, "offset": 0, "textws": "She " },
                { "i": 1, "offset": 4, "textws": "has " },
                { "i": 2, "offset": 8, "textws": "ready" },
                { "i": 3, "offset": 13, "textws": "." },
                { "i": 4, "offset": 14, "textws": "\n" }
            ]
        },
        {}
    ],
    "total": 4
}

Field	Type	Required	Description
data	object[]	Yes	Per-sentence data objects
total	number	Yes	Total error count

Each object in data contains one sentence's results
edits[i].itok is the token index in toks, enabling replacement

Field	Type	Required	Description
snt	string	Yes	Sentence text
edits	object[]	Yes	Correction suggestions
edits[i].offset	number	Yes	Character offset in sentence
edits[i].itok	number	Yes	Token index in `toks`
edits[i].orig	string	Yes	Original token
edits[i].corr	string	Yes	Corrected token
edits[i].type	R,M,U	Yes	R=replace, M=insert, U=delete
edits[i].cate	string	Yes	Error category
edits[i].of	string	No	Localized error category
edits[i].shortmsg	string	Yes	Suggestion
toks	object[]	Yes	Token positions
toks[i].i	number	Yes	Token index in sentence
toks[i].offset	number	No	Character position in sentence
toks[i].textws	string	Yes	Token with trailing space

export interface editType {  
    "offset": number
    "itok": number        // start position in toks
    "iend": number        // end position (exclusive) in toks
    "orig": string
    "corr": string
    "type": "R"|"M"|"U"  // R=replace, M=insert, U=delete
    "cate": string
    "of"?: string         // localized category
    "shortmsg": string    // suggestion
    isModify?: boolean    // whether modified — add this field yourself
    cands?: string[]      // replacement candidates when there are many options
    context?: any[]       // replacement context; indices 0|1 are number, 2 is string
}

export interface editType {  
    "offset": number
    "itok": number        // start position in toks
    "iend": number        // end position (exclusive) in toks
    "orig": string
    "corr": string
    "type": "R"|"M"|"U"  // R=replace, M=insert, U=delete
    "cate": string
    "of"?: string         // localized category
    "shortmsg": string    // suggestion
    isModify?: boolean    // whether modified — add this field yourself
    cands?: string[]      // replacement candidates when there are many options
    context?: any[]       // replacement context; indices 0|1 are number, 2 is string
}

4. Warning Endpoint

Endpoint: POST https://url_cn/wpsv2-warn
URL names accepts two values: xsntwarn and xsntflue, comma-separated: names=urlencode(xsntwarn,xsntflue)
Additional types may be added to names in the future; omitting it uses defaults

Request:

json

{
    "snts": [
        "She has ready.\n",
        "I pay attention to the box.",
        "This are gramamtical sentence."
    ]
}

{
    "snts": [
        "She has ready.\n",
        "I pay attention to the box.",
        "This are gramamtical sentence."
    ]
}

Field	Type	Required	Description
snts	string[]	Yes	Sentences after splitting

Response:

json

{
  "total": 5,
  "items": {
    "xsntwarn": 2,
    "xsntflue": 3
  },
  "data": {
    "xsntwarn": [
      [],
      [
        {
          "type": "NP",
          "offset": 6,
          "wordlist": "a big boxe",
          "shortmsg": "<b>a big boxe</b> is rarely used by native speakers",
          "by": "gramoov"
        }
      ],
      [
        {
          "type": "word",
          "pos": "NOUN",
          "ibeg": 2,
          "offset": 7,
          "wordlist": "traffics",
          "shortmsg": "<b>traffics</b> is not normally used in plural form",
          "by": "noun_noplual"
        }
      ]
    ],
    "xsntflue": [
      [
        {
          "type": "sent",
          "snt": "She has ready.",
          "flue": 0.056,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ],
      [
        {
          "type": "sent",
          "snt": "It is a big boxe.",
          "flue": 0.4247,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ],
      [
        {
          "type": "sent",
          "snt": "It are traffics.",
          "flue": 0.0425,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ]
    ]
  }
}

{
  "total": 5,
  "items": {
    "xsntwarn": 2,
    "xsntflue": 3
  },
  "data": {
    "xsntwarn": [
      [],
      [
        {
          "type": "NP",
          "offset": 6,
          "wordlist": "a big boxe",
          "shortmsg": "<b>a big boxe</b> is rarely used by native speakers",
          "by": "gramoov"
        }
      ],
      [
        {
          "type": "word",
          "pos": "NOUN",
          "ibeg": 2,
          "offset": 7,
          "wordlist": "traffics",
          "shortmsg": "<b>traffics</b> is not normally used in plural form",
          "by": "noun_noplual"
        }
      ]
    ],
    "xsntflue": [
      [
        {
          "type": "sent",
          "snt": "She has ready.",
          "flue": 0.056,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ],
      [
        {
          "type": "sent",
          "snt": "It is a big boxe.",
          "flue": 0.4247,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ],
      [
        {
          "type": "sent",
          "snt": "It are traffics.",
          "flue": 0.0425,
          "by": "xsntflue",
          "shortmsg": "Please check the syntax of this sentence"
        }
      ]
    ]
  }
}

Field	Type	Required	Description
total	number	Yes	Total warning count
items	object	No	Per-category counts
data	object	Yes	Warning data

data.xsntwarn — sentence-level warnings; data.xsntflue — fluency warnings
Both are arrays of arrays, one per sentence

interface xsntwarnType {
    "type": string
    "offset"?: number
    "wordlist": string    // matched word or phrase
    "shortmsg": string    // tip message
    "by": string          // engine module name
}

interface xsntwarnType {
    "type": string
    "offset"?: number
    "wordlist": string    // matched word or phrase
    "shortmsg": string    // tip message
    "by": string          // engine module name
}

interface xsntflueType {
    "type": string
    "snt": string         // sentence
    "flue": number        // fluency score
    "by"?: string         // engine module name
    "shortmsg": string    // suggestion
}

interface xsntflueType {
    "type": string
    "snt": string         // sentence
    "flue": number        // fluency score
    "by"?: string         // engine module name
    "shortmsg": string    // suggestion
}

5. Tip Endpoint

Endpoint: POST https://url_cn/wpsv2-tip
URL names accepts two values: xcloze and xchunk, comma-separated: names=urlencode(xcloze,xchunk)
Additional types may be added in the future; omitting uses defaults

Request:

json

{
  "snts": [
    "I am too tired to move on.",
    "I pay attention to the box."
  ],
  "topk": 10
}

{
  "snts": [
    "I am too tired to move on.",
    "I pay attention to the box."
  ],
  "topk": 10
}

Field	Type	Required	Description
snts	string[]	Yes	Sentences after splitting
topk	number	No	Number of tip suggestions

Response:

json

{
  "total": 4,
  "items": {
    "xcloze": 2,
    "xchunk": 2
  },
  "data": {
    "xcloze": [
      [
        {
          "word": "tired",
          "sentiment": 0,
          "cands": [
            ["weak", 0.0283, 0.2589],
            ["hungry", 0.0134, 0.4132]
          ]
        }
      ],
      [
        {
          "word": "box",
          "sentiment": 0,
          "cands": [
            ["clock", 0.0438, 0.0791],
            ["surroundings", 0.0142, 0.0502],
            ["noise", 0.0135, 0.0323],
            []
          ]
        }
      ]
    ],
    "xchunk": [
      [],
      [
        {
          "ibeg": 1,
          "iend": 4,
          "tag": "_jj",
          "offset": 1,
          "pattern": "pay _jj attention to",
          "cands": [
            ["close", "195392"],
            ["particular", "159440"],
            []
          ]
        },
        {
          "ibeg": 4,
          "iend": 6,
          "tag": "_jj",
          "offset": 1,
          "pattern": "the _jj box",
          "cands": [
            ["appropriate", "250394"],
            ["original", "167511"]
          ]
        }
      ]
    ]
  }
}

{
  "total": 4,
  "items": {
    "xcloze": 2,
    "xchunk": 2
  },
  "data": {
    "xcloze": [
      [
        {
          "word": "tired",
          "sentiment": 0,
          "cands": [
            ["weak", 0.0283, 0.2589],
            ["hungry", 0.0134, 0.4132]
          ]
        }
      ],
      [
        {
          "word": "box",
          "sentiment": 0,
          "cands": [
            ["clock", 0.0438, 0.0791],
            ["surroundings", 0.0142, 0.0502],
            ["noise", 0.0135, 0.0323],
            []
          ]
        }
      ]
    ],
    "xchunk": [
      [],
      [
        {
          "ibeg": 1,
          "iend": 4,
          "tag": "_jj",
          "offset": 1,
          "pattern": "pay _jj attention to",
          "cands": [
            ["close", "195392"],
            ["particular", "159440"],
            []
          ]
        },
        {
          "ibeg": 4,
          "iend": 6,
          "tag": "_jj",
          "offset": 1,
          "pattern": "the _jj box",
          "cands": [
            ["appropriate", "250394"],
            ["original", "167511"]
          ]
        }
      ]
    ]
  }
}

Field	Type	Required	Description
total	number	Yes	Total tip count
items	object	No	Per-category counts
data	object	Yes	Tip data

data.xcloze — synonym suggestions; data.xchunk — chunk-level suggestions; data.xconfusion — confusion word suggestions
Each is an array of arrays, one per sentence

interface xclozeType {
    "word": string          // candidate replacement word
    "sentiment": -1|0|1     // -1=negative, 0=neutral, 1=positive
    "cands": any[][]        // [0]=candidate, [1]=sentence relevance, [2]=word distance
}

interface xclozeType {
    "word": string          // candidate replacement word
    "sentiment": -1|0|1     // -1=negative, 0=neutral, 1=positive
    "cands": any[][]        // [0]=candidate, [1]=sentence relevance, [2]=word distance
}

interface xchunkType {
    "ibeg"?: number,
    "iend"?: number,
    "tag": string,          // replacement slot
    "offset": number,
    "pattern": string,      // chunk pattern
    "cands": string[][]     // take index [0] from each inner array
}

interface xchunkType {
    "ibeg"?: number,
    "iend"?: number,
    "tag": string,          // replacement slot
    "offset": number,
    "pattern": string,      // chunk pattern
    "cands": string[][]     // take index [0] from each inner array
}

6. Combined Error + Warning + Tip Endpoint

Endpoint: POST https://url_cn/wpsv2?timeout=6

6.1 Request

timeout — timeout in seconds, default 6s

json

{
  "snts": [
    "She has ready.",
    "Traffics is a big boxe."
  ] 
}

{
  "snts": [
    "She has ready.",
    "Traffics is a big boxe."
  ] 
}

Field	Type	Required	Description
snts	string[]	Yes	Sentences after splitting

6.2 Response

json

{
    "snts": ["She has ready.", "Traffics is a big boxe."],
    "err": ["xsntedits"],
    "warn": ["xsntwarn", "xsntflue"],
    "tip": ["xcloze", "xchunk", "xconfusion"],
    "default": ["xsnttoks"],
    "items": {
        "xsnttoks": 10,
        "xsntedits": 3,
        "xsntwarn": 2,
        "xsntflue": 2,
        "xcloze": 1,
        "xchunk": 0,
        "xconfusion": 1
    },
    "xsnttoks": [[...], [...]],
    "xsntedits": [[...], [...]],
    "xsntwarn": [[], [...]],
    "xsntflue": [[...], [...]],
    "xcloze": [[], [...]],
    "xchunk": [[], []],
    "xconfusion": [[], [...]],
    "total": { "err": 3, "warn": 4, "tip": 2 },
    "time": {
        "xsnttoks": 0.0021,
        "xsntedits": 0.0017,
        "xsntwarn": 0.0046,
        "xsntflue": 0.0415,
        "xcloze": 0.0431,
        "xchunk": 0.0321,
        "xconfusion": 0.0028,
        "total": 0.05
    }
}

{
    "snts": ["She has ready.", "Traffics is a big boxe."],
    "err": ["xsntedits"],
    "warn": ["xsntwarn", "xsntflue"],
    "tip": ["xcloze", "xchunk", "xconfusion"],
    "default": ["xsnttoks"],
    "items": {
        "xsnttoks": 10,
        "xsntedits": 3,
        "xsntwarn": 2,
        "xsntflue": 2,
        "xcloze": 1,
        "xchunk": 0,
        "xconfusion": 1
    },
    "xsnttoks": [[...], [...]],
    "xsntedits": [[...], [...]],
    "xsntwarn": [[], [...]],
    "xsntflue": [[...], [...]],
    "xcloze": [[], [...]],
    "xchunk": [[], []],
    "xconfusion": [[], [...]],
    "total": { "err": 3, "warn": 4, "tip": 2 },
    "time": {
        "xsnttoks": 0.0021,
        "xsntedits": 0.0017,
        "xsntwarn": 0.0046,
        "xsntflue": 0.0415,
        "xcloze": 0.0431,
        "xchunk": 0.0321,
        "xconfusion": 0.0028,
        "total": 0.05
    }
}

6.3 Response Field Reference

Field	Type	Description
err	string[]	Error fields — may contain `xsntedits`
warn	string[]	Warning fields — may contain `xsntwarn`, `xsntflue`
tip	string[]	Tip fields — may contain `xcloze`, `xchunk`, `xconfusion`
total	totalType	Totals for `err`, `warn`, `tip`
items	itemsType	Per-category counts
xsnttoks	toksType[][]	Tokenized data with spaces; outer index = sentence, inner = token
xsntedits	editType[][]	Outer = sentence, inner = edit
xsntwarn	xsntwarnType[][]	Outer = sentence, inner = warning
xconfusion	confusionType[][]	Outer = sentence, inner = confusion item
xsntflue	flueType[][]	Outer = sentence, inner = fluency item
xcloze	xclozeType[][]	Outer = sentence, inner = cloze tip
xchunk	xchunkType[][]	Outer = sentence, inner = chunk tip
time	timeType	Timing breakdown

Type Definitions

`totalType`

interface totalType { 
    "err": number
    "warn": number
    "tip": number
}

interface totalType { 
    "err": number
    "warn": number
    "tip": number
}

`itemsType`

interface itemsType {
    "xsnttoks": number
    "xsntedits": number
    "xsntwarn": number
    "xsntflue": number
    "xcloze": number
    "xchunk": number
    "xconfusion": number
}

interface itemsType {
    "xsnttoks": number
    "xsntedits": number
    "xsntwarn": number
    "xsntflue": number
    "xcloze": number
    "xchunk": number
    "xconfusion": number
}

`toksType`

interface toksType { 
    "i": number       // token index in sentence
    "offset": number  // character position in sentence
    "textws": string  // token with trailing space
}

interface toksType { 
    "i": number       // token index in sentence
    "offset": number  // character position in sentence
    "textws": string  // token with trailing space
}

`editType`

export interface editType {  
    "offset": number
    "itok": number
    "iend": number
    "orig": string
    "corr": string
    "type": "R"|"M"|"U"
    "cate": string
    "of"?: string
    "shortmsg": string
    isModify?: boolean
    cands?: string[]
    context?: any[]
}

export interface editType {  
    "offset": number
    "itok": number
    "iend": number
    "orig": string
    "corr": string
    "type": "R"|"M"|"U"
    "cate": string
    "of"?: string
    "shortmsg": string
    isModify?: boolean
    cands?: string[]
    context?: any[]
}

`xclozeType`

interface xclozeType {
    "word": string
    "sentiment": -1|0|1
    "cands": any[][]
}

interface xclozeType {
    "word": string
    "sentiment": -1|0|1
    "cands": any[][]
}

`xchunkType`

interface xchunkType {
    "ibeg"?: number,
    "iend"?: number,
    "tag": string,
    "offset": number,
    "pattern": string,
    "cands": string[][]
}

interface xchunkType {
    "ibeg"?: number,
    "iend"?: number,
    "tag": string,
    "offset": number,
    "pattern": string,
    "cands": string[][]
}

`xsntwarnType`

interface xsntwarnType {
    "type": string
    "offset"?: number
    "wordlist": string
    "shortmsg": string
    "by": string
}

interface xsntwarnType {
    "type": string
    "offset"?: number
    "wordlist": string
    "shortmsg": string
    "by": string
}

`flueType`

interface flueType {
    "type": string
    "snt": string
    "flue": number
    "by": string
}

interface flueType {
    "type": string
    "snt": string
    "flue": number
    "by": string
}

`confusionType`

interface confusionType {
    "word": string
    "lemma": string
    "pos": string
    "ibeg": number
    "offset": number
    "of": string
    "cands": string[]
}

interface confusionType {
    "word": string
    "lemma": string
    "pos": string
    "ibeg": number
    "offset": number
    "of": string
    "cands": string[]
}

`timeType`

interface timeType {
    "xsnttoks"?: number
    "xsntedits"?: number
    "xsntwarn"?: number
    "xsntflue"?: number
    "xcloze"?: number
    "xchunk"?: number
    "xconfusion"?: number
    "total": number
}

interface timeType {
    "xsnttoks"?: number
    "xsntedits"?: number
    "xsntwarn"?: number
    "xsntflue"?: number
    "xcloze"?: number
    "xchunk"?: number
    "xconfusion"?: number
    "total": number
}

WPS Partnership API V2 ​

1. Overview ​

Authentication ​

Conventions ​

Flow ​

Environments ​

2. Sentence Splitting Endpoint ​

3. Error Endpoint ​

4. Warning Endpoint ​

5. Tip Endpoint ​

6. Combined Error + Warning + Tip Endpoint ​

6.1 Request ​

6.2 Response ​

6.3 Response Field Reference ​

Type Definitions ​

totalType ​

itemsType ​

toksType ​

editType ​

xclozeType ​

xchunkType ​

xsntwarnType ​

flueType ​

confusionType ​

timeType ​

WPS Partnership API V2

1. Overview

Authentication

Conventions

Flow

Environments

2. Sentence Splitting Endpoint

3. Error Endpoint

4. Warning Endpoint

5. Tip Endpoint

6. Combined Error + Warning + Tip Endpoint

6.1 Request

6.2 Response

6.3 Response Field Reference

Type Definitions

`totalType`

`itemsType`

`toksType`

`editType`

`xclozeType`

`xchunkType`

`xsntwarnType`

`flueType`

`confusionType`

`timeType`