Real-time (synchronous) coding
Single record and small batch coding.
The coding service has been designed to apply a classification code and title to a free text entry. The single record coding feature will enable public facing webforms and other points of data collection to have codes and titles suggested in real time (~1 second).
A small JSON file of up to 300 text records can also be coded synchronously.
Note: when you are running a synchronous small batch, the whole packet needs to be syntactically correct. If the syntax fails, the whole batch will fail. As the operation is combined for the whole group of records, none of the records will be able to be coded if there is an error in any record.
When to use synchronous or asynchronous coding
Synchronous coding should only be used for single record coding or small batches of data. If you are coding 900 records, for example, it will be possible to run them in three small batch submissions.
Asynchronous large batch coding is recommended if you need to code or recode a large volume of data. (Large batch coding can be used to code from 1 record to millions of records.)
Coding against the latest model for a topic
This endpoint is used to code a single or small batch of free text records against the specified coding topic, using the latest model for that topic.
Request syntax
Depending on whether you are coding a single record or a small batch of records, your request will follow one of the following formats:
1. Coding a single free text record
POST /v1/topics/{topic}/code HTTP/1.1
Host: string
Content-type: application/json
Authorisation: string
{
"record": {
"occp_text": "string",
"tasks_text": "string"
},
"numberOfSuggestions": number
}
2. Coding a small batch of free text records
POST /v1/topics/{topic}/code HTTP/1.1
Host: string
Content-type: application/json
Authorisation: string
{
"records": [
{
"recordId": "string",
"occp_text": "string",
"tasks_text": "string"
},
],
"numberOfSuggestions": number
}
| topic | The uriName of the topic against which the record is coded. This can be acquired by listing the available topics. Required: Yes |
|---|
| record | The free text record to be coded. Type: Record object, following the input format specified by the model. Required: No, but either record or records must be provided. |
|---|---|
| records | The free text records to be coded. Type: Array of Record objects, following the input format specified by the model. Each item may optionally specify an additional string value recordId. Length Constraints: Minimum length of 1. Maximum length of 300. Required: No, but either record or records must be provided. |
| numberOfSuggestions | The number of suggested codes to be provided if the record cannot be coded successfully. The maximum value of this field is 16. Type: Number Required: No |
Response syntax
The response of this endpoint will depend on whether your input request contained a single record or a small batch of records.
1. Coding a single free text record
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "string",
"input": {
"occp_text": "string",
"tasks_text": "string"
},
"result": [
{
"codeCategory": "string",
"codeLabel": "string",
"codeConfidence": number
}
],
}
2. Coding a small batch of free text records
HTTP/1.1 200 OK
Content-type: application/json
[
{
"recordId": "string",
"codeStatus": "string",
"input": {
"occp_text": "string",
"tasks_text": "string"
},
"result": [
{
"codeCategory": "string",
"codeLabel": "string",
"codeConfidence": number
}
],
}
]
Response elements
If the action is successful, the service sends back an HTTP 200 response. The API returns either a SynchronousCodeResponse object or an array of SynchronousCodeResponse objects corresponding to the input records.
Errors
For information about the errors that are common to all actions, see Errors and suggested actions. The following errors may occur when calling this service:
Examples
Successfully coded a single record using only one free text field:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"record": {
"occp_text": "Software developer. Writes code, tests"
},
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "successful",
"input": {
"occp_text": "Software developer. Writes code, tests"
},
"result": [{
"codeCategory": "261313",
"codeLabel": "Software Engineer",
"codeConfidence": 0.6093962788581848
},{
"codeCategory": "261312",
"codeLabel": "Developer Programmer",
"codeConfidence": 0.43940293565392494
},{
"codeCategory": "261399",
"codeLabel": "Software and Applications Programmers nec",
"codeConfidence": 0.43756575286388397
}]
}
Successfully coded a single record using all free text fields:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"record": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "successful",
"input": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"result": [{
"codeCategory": "261313",
"codeLabel": "Software Engineer",
"codeConfidence": 0.6093962788581848
},{
"codeCategory": "261312",
"codeLabel": "Developer Programmer",
"codeConfidence": 0.43940293565392494
},{
"codeCategory": "261399",
"codeLabel": "Software and Applications Programmers nec",
"codeConfidence": 0.43756575286388397
}]
}
Unsuccessfully coded a single record using only one free text field:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"record": {
"occp_text": "Software developer. Writes code, tests"
},
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "unsuccessful",
"input": {
"occp_text": "Software developer. Writes code, tests"
},
"result": [ ]
}
Coding a small batch of records:
Sample request
POST /v1/topics/osca/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"records": [
{
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
}, {
"occp_text": "Paramedic, respond to emergencies"
}, {
"recordId": "1",
"occp_text": "Sales assistant"
}
],
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
[
{
"codeStatus": "successful",
"input": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"result": [{
"codeCategory": "261313",
"codeLabel": "Software Engineer",
"codeConfidence": 0.6093962788581848
},{
"codeCategory": "261312",
"codeLabel": "Developer Programmer",
"codeConfidence": 0.43940293565392494
},{
"codeCategory": "261399",
"codeLabel": "Software and Applications Programmers",
"codeConfidence": 0.43756575286388397
}]
}, {
"codeStatus": "unsuccessful",
"input": {
"occp_text": "Paramedic, respond to emergencies"
},
"result": [ ]
}, {
"recordId": "1",
"codeStatus": "unsuccessful",
"input": {
"occp_text": "Sales assistant"
},
"result": [ ]
}
]
Coding against a specific model
This endpoint is used to code a single or small batch of free text records against the specified coding topic, using the specified model.
Request syntax
Depending on whether you are coding a single record or a small batch of records, your request will follow one of the following formats:
1. Coding a single free text record against a specific model
POST /v1/topics/{topic}/models/{model}/code HTTP/1.1
Host: string
Content-type: application/json
Authorisation: string
{
"record": {
"occp_text": "string",
"tasks_text": "string"
}
"numberOfSuggestions": number
}
2. Coding records against a specific model
POST /v1/topics/{topic}/models/{model}/code HTTP/1.1
Host: string
Content-type: application/json
Authorisation: string
{
"records": [
{
"recordId": "string",
"occp_text": "string",
"tasks_text": "string"
}
],
"numberOfSuggestions": number
}
| topic | The uriName of the topic against which the record is coded. This can be acquired by listing the available topics. Required: Yes |
|---|---|
| model | The model GUID for the model you would like to use to code records. This can be acquired by listing the available models for your topic. Required: Yes |
| record | The free text record to be coded. Type: Record object, following the input format specified by the model. Required: No, but either record or records must be provided. |
|---|---|
| records | The free text records to be coded. Type: Array of Record objects, following the input format specified by the model. Each item may optionally specify an additional string value recordId. Length Constraints: Minimum length of 1. Maximum length of 300. Required: No, but either record or records must be provided. |
| numberOfSuggestions | The number of suggested codes to be provided if the record cannot be coded successfully. The maximum value of this field is 16. Type: Number Required: No |
Response syntax
The response of this endpoint will depend on whether your input request contained a single record or a small batch of records.
1. Coding a single free text record
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "string",
"input": {
"occp_text": "string",
"tasks_text": "string"
},
"result": [
{
"codeCategory": "string",
"codeLabel": "string",
"codeConfidence": number
}
],
}
2. Coding a small batch of free text records
HTTP/1.1 200 OK
Content-type: application/json
[
{
"recordId": "string",
"codeStatus": "string",
"input": {
"occp_text": "string",
"tasks_text": "string"
},
"result": [
{
"codeCategory": "string",
"codeLabel": "string",
"codeConfidence": number
}
],
}
]
Response elements
If the action is successful, the service sends back an HTTP 200 response. The API returns either a SynchronousCodeResponse object or an array of SynchronousCodeResponse objects corresponding to the input records.
For information about the errors that are common to all actions, see Errors and suggested actions. The following errors may occur when calling this service:
| Malformed record found in request | The free text input did not match the expected format for the model. You can check what the expected format is for a given topic here. HTTP Status Code: 400 (Bad Request) |
|---|---|
| Batch input contained no records | You tried to code a small batch of records but the records array was empty. Check that you have provided at least one record to be coded and that your request body is correctly formatted. HTTP Status Code: 400 (Bad Request) |
| Batch records exceeds length limit of 300 | You tried to code too many records at once using the synchronous small batch service. Retry with a smaller batch size, or consider using the asynchronous batch coding service. HTTP Status Code: 400 (Bad Request) |
| There are record(s) outside the min or max char limit | One or more records provided for synchronous coding had too many or too few characters. See Recommended text input for coding. The error will direct you to the problematic record(s) which should either be excluded or amended to meet the character limits. HTTP Status Code: 400 (Bad Request) |
Examples
Successfully coded a single record using all free text fields:
Sample request
POST /v1/topics/osca/models/GUID/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"record": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
{
"codeStatus": "successful",
"input": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"result": [{
"codeCategory": "261313",
"codeLabel": "Software Engineer",
"codeConfidence": 0.6093962788581848
},{
"codeCategory": "261312",
"codeLabel": "Developer Programmer",
"codeConfidence": 0.43940293565392494
},{
"codeCategory": "261399",
"codeLabel": "Software and Applications Programmers nec",
"codeConfidence": 0.43756575286388397
}]
}
Coding a small batch of records:
Sample request
POST /v1/topics/osca/models/GUID/code HTTP/1.1
Host: https://partner-coder.api.abs.gov.au
Content-type: application/json
Authorisation: example token
{
"records": [
{
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
}, {
"occp_text": "Paramedic, respond to emergencies"
}, {
"recordId": "1",
"occp_text": "Sales assistant"
}
],
"numberOfSuggestions": 3
}
Sample response
HTTP/1.1 200 OK
Content-type: application/json
[
{
"codeStatus": "successful",
"input": {
"occp_text": "software developer",
"tasks_text": "writing code and unit tests"
},
"result": [{
"codeCategory": "261313",
"codeLabel": "Software Engineer",
"codeConfidence": 0.6093962788581848
},{
"codeCategory": "261312",
"codeLabel": "Developer Programmer",
"codeConfidence": 0.43940293565392494
},{
"codeCategory": "261399",
"codeLabel": "Software and Applications Programmers",
"codeConfidence": 0.43756575286388397
}]
}, {
"codeStatus": "unsuccessful",
"input": {
"occp_text": "Paramedic, respond to emergencies"
},
"result": [ ]
}, {
"recordId": "1",
"codeStatus": "unsuccessful",
"input": {
"occp_text": "Sales assistant"
},
"result": [ ]
}
]