Classifier API Documentation © 2024 Convergence Research, Inc.

Introduction - Charge Classifier

The Charge Classifier service is a web API that allows an integrator to submit a charge to Convergence Research for classification using a machine-learning algorithm developed from the vast collection of classified charges housed internally. It is trained daily by the Convergence Research staff and models are re-built nightly.

The web API uses a Json Web Token method for authentication and accepts input/output in both XML and JSON. Once issued, tokens have a 24 hour validity period. The following is an example workflow of a classification request:

Availability

Although the models are re-built nightly, this should not result in an interuption of service. However, we reserve the following times for maintenance:

Nightly - Monday-Friday 12:30AM to 12:45AM EST
Weekly - Sunday 12:30AM to 1:30AM

Support

Support is available M-F from 8:00AM to 5:00PM for non-critical issues using the following contact information:

Email: support@convergenceresearch.com
Phone: 866.606.4023

NOTE: If your issue is critical and is impacting production, please use it@convergenceresearch.com to open a support ticket.

Request/Response Formats and Status Codes

The API will recognize both XML and JSON for requests and responses. NOTE: Although very similar, there are slight differences in casing and word separation between the two formats. Please be sure to consult the object definitions.

Http Status Codes

Http Status codes are used to communicate the success or failure of any operation. The following status codes can be returned by the service:

200 OK The operation succeeded and, if a response is expected, it will be found in the response body
202 Accepted The request passed validation but the ML learning model is being re-built. This only occurs if the model is being replaced on the web server. The request will not process and will need to be re-submitted.
400 Bad Request Something is incorrect with the request. The request could be missing required fields or the http method might not be appropriate. Consult the documentation. The http response text will have the reason as to why the request was rejected.
401 Unauthorized The JWT token is missing or invalid. Re-request a new token and attach it to the 'Authorization Bearer' header
500 Internal Server Error The request failed and the reason is indeterminate. Please contact support.
503 Service Unavailable There is an unexpected problem with the service concerning the ML model that wouldn't allow it to start. Please contact support.

Request/Response Format

The API uses content negotiation to determine whether json or xml is returned from an API call. If the format is not specified, JSON is the default response format.

The Content-type and Accept Http headers are what content negotiation uses to parse requests and serialize responses to the http content stream. NOTE: You can mix and match the Accept and Content-type if you want a different response format from the request and vice-versa.

Here are some examples of using the Http request headers to dictate the format:

Http Headers - JSON Request expecting a JSON response

                                    
        Host: ml.convergenceresearch.com
        Content-type: application/json
        Accept: application/json                                             
        Content-Length: 54

Http Headers - XML Request expecting a XML response

                                    
        Host: ml.convergenceresearch.com
        Content-type: application/xml
        Accept: application/xml                                             
        Content-Length: 54

Http Headers - XML Request expecting a JSON response

                                    
        Host: ml.convergenceresearch.com
        Content-type: application/xml
        Accept: application/json                                             
        Content-Length: 54

API Methods Available

All API method calls are to be made over https/ssl with the appropriate http verb. If you receive a 404 Not Found http response, be sure to check that the verb is correct.

RequestJWTToken

Description:	This method is token request that issues integrators an API token valid for 24 hours.
Url:	api/classifier/requestjwttoken
Http Verb:	POST
Request Object:	TokenRequest
Response Object	JwtSecurityToken
Possible Status Codes:	400 Bad Request 200 OK
Remarks:	The response token MUST be attached as the `Authorization Bearer` header in all subsequent requests. The token is valid for 24 hours from issuance.
Example Request:	`POST https://ml.convergenceresearch.com/api/Classifier/RequestJWTToken HTTP/1.1 Host: ml.convergenceresearch.com Content-Length: 77 Content-Type: application/json Accept: application/json { apiname: "chargeclassifier", key: "HG567JQ3344565BG45XC" }`
Example Response:	`HTTP/1.1 200 OK Date: Thu, 27 Feb 2020 12:50:30 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 399 {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUElLZXlJRCI6IjEiLCJodHRwOi8vc2No"}`

CheckStatus

Description:	This method provides status information about the API and can be used to check the status of the ML model.
Url:	api/classifier/checkstatus
Http Verb:	GET
Request Object:	N/A
Response Object:	StatusResponse
Possible Status Codes:	200 OK 202 Accepted 503 Service Unavailable 500 Internal Server Error
Remarks:	Any response besides a `200 OK` means the service is unavailable. A `202 Accepted` response means to try again shortly as the model is being built.
Example Request:	`GET https://ml.convergenceresearch.com/api/Classifier/CheckStatus HTTP/1.1 Host: ml.convergenceresearch.com Content-Length: 0 Content-Type: application/json Accept: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUE`
Example Response	`HTTP/1.1 200 OK Date: Tue, 03 Mar 2020 20:07:33 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 48 {"status":"Ready","message":"Service is ready."}`

GetStopWords

Description:	The method will return the current stop words the API uses to format incoming text. This list is maintained by Convergence Research.
Url:	api/classifier/getstopwords
Http Verb:	GET
Request Object:	N/A
Response Object:	Array of string
Possible Status Codes:	200 OK 500 Internal Server Error
Remarks:	The response object is a list of strings
Example Request:	`GET https://ml.convergenceresearch.com/api/Classifier/GetStopWords HTTP/1.1 Host: ml.convergenceresearch.com Content-Length: 0 Content-Type: application/json Accept: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUEl`
Example Response:	`HTTP/1.1 200 OK Date: Tue, 03 Mar 2020 20:28:29 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 6708 ["able","about","above","abroad","according"]`

CategoryInfo

Description:	This method provides information about the defined categories as well overall statistics regarding macro/micro accuracy, log loss and reduction.
Url:	api/classifier/categoryinfo
Http Verb:	GET
Request Object:	N/A
Response Object:	CategoryDetails
Possible Status Codes:	200 OK 500 Internal Server Error
Remarks:	The statistics also provide a list of the category names/ids. This is useful if you need to filter the categories to only the ones you are interested in when making a request.
Example Request:	`GET https://ml.convergenceresearch.com/api/Classifier/CategoryInfo HTTP/1.1 Host: ml.convergenceresearch.com Content-Length: 0 Content-Type: application/json Accept: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUElLZXlJRCI6IjEiL`
Example Response:	HTTP/1.1 200 OK Date: Tue, 03 Mar 2020 20:53:20 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 13132 { "timestamp": "2020-03-03T15:53:21.0770524-05:00", "allstatistics": { "macroaccuracy": "95.9010%", "microaccuracy": "97.0800%", "logloss": "11.3987%", "logreduction": "88.2067%" }, "categories": [{ "categoryid": 88, "name": "Sex Offenses", "crimeagainst": ["Person"], "traincount": 55, "status": "Ready", "trainingstarted": "2020-03-02T13:07:19.2653021-05:00", "trainingfinished": "2020-03-02T13:07:43.2176393-05:00", "statistics": { "macroaccuracy": "93.2840%", "microaccuracy": "97.7646%", "logloss": "7.1462%", "logreduction": "89.7724%" } }, { "categoryid": 92, "name": "Bad Checks", "crimeagainst": ["Person"], "traincount": 263, "status": "Ready", "trainingstarted": "2020-03-02T13:07:19.3492991-05:00", "trainingfinished": "2020-03-02T13:07:43.1626447-05:00", "statistics": { "macroaccuracy": "97.6411%", "microaccuracy": "97.7936%", "logloss": "7.4359%", "logreduction": "90.0014%" } } ......snipped for brevity .... ] }

TrainingRequest

Description:	If there are terms you would like to be classified for future results, you can submit them through this method and they will be examined and trained.
Url:	api/classifier/trainingrequest
Http Verb:	POST
Request Object:	TrainingRequest
Response Object:	TrainingResponse
Possible Status Codes:	200 OK 400 Bad Request 500 Internal Server Error
Remarks:	The amount of items that can be submitted is based on how many requests you've made in the last 30 days at a 1-to-10 ratio. For example, if you've submitted 500 requests in the last 30 days, you can request training on 50 items. Items must be distinct. If you've already submitted an item for training and you resubmit it, it will reflect a status of 'AlreadyQueued' in the response object.
Example Request:	`POST https://ml.convergenceresearch.com/api/Classifier/TrainingRequest HTTP/1.1 Host: ml.convergenceresearch.com Content-type: application/json Accept: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUElL Content-Length: 54 { "charges": [ "drunk and disorderly" ] }`
Example Response:	`HTTP/1.1 200 OK Date: Thu, 27 Feb 2020 13:56:07 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 117 {"items":[{"status":"Accepted","timestamp":"2020-02-27T08:56:00.2643718-05:00","chargetext":"drunk and disorderly"}]}`

Criminal

Description:	This method performs the classification on the source text you submit and returns the categor(ies) that match.
Url:	api/classifier/criminal
Http Verb:	POST
Request Object:	ClassifierRequest
Response Object:	ClassifierResponse
Possible Status Codes:	200 OK 202 Accepted 400 Bad Request 500 Internal Server Error
Remarks:	If the model is being re-built at the time of the call, you could receive a 202 response. You should re-submit the request and it should succeed. This only occurs during the maintenance window of 12:15 AM EST to 12:25 AM.
Example Request:	`POST https://ml.convergenceresearch.com/api/Classifier/Criminal HTTP/1.1 Content-type: application/json Accept: application/json Host: ml.convergenceresearch.com Content-Length: 74 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUElLZXlJRCI6IjEiLCJodHRwOi8vc2 { "sourcetext": "Drunk in public", "requiredconfidence": 0.95 }`
Example Response:	HTTP/1.1 200 OK Date: Tue, 03 Mar 2020 21:24:19 GMT Content-Type: application/json; charset=utf-8 Server: Kestrel Content-Length: 3827 { "timestamp": "2020-03-03T16:24:16.688107-05:00", "classifications": [{ "term": "Drunk in public", "predictions": ["All Other Offenses", "Drunkeness"], "categories": [{ "crimeagainst": ["Person"], "category": "Drunkeness", "ismatch": true, "score": "99.99%" }, { "crimeagainst": ["Person"], "category": "All Other Offenses", "ismatch": true, "score": "98.31%" }, { "crimeagainst": ["Society"], "category": "Drug/Narcotic Offenses", "ismatch": false, "score": "3.01%" }, { "crimeagainst": ["Person"], "category": "Liquor Law Violations", "ismatch": false, "score": "22.51%" }, { "crimeagainst": ["Person"], "category": "Driving Under the Influence", "ismatch": false, "score": "1.21%" }, { "crimeagainst": ["Person"], "category": "Kidnapping/Abduction", "ismatch": false, "score": "0.01%" }, { "crimeagainst": ["Society"], "category": "Animal Cruelty", "ismatch": false, "score": "0.01%" }] ...snipped for brevity ... }] }

Object Definitions

All objects are serializable as both xml and json. Examples of each object can be downloaded for review. NOTE: TokenResponse is never returned as xml regardless of the value of your Accept header. Since TokenResponse is a Json Web Token it is always returned as JSON

TokenRequest

The TokenRequest method issues Json Web Tokens to authenticated clients.

XML Example

                                    
        <request-token>
        <api-name>chargeclassifier</api-name>
        <key>E85B37C58958DA46AF0C487598596</key>
        </request-token>

JSON Example

                                        
    {
    "apiname": "chargeclassifier",
    "key": "E85B37C58958DA46AF0C487598596"
    }

Field Name	Type	Required	XML Name	JSON Name	Comments
ApiName	string		api-name	apiname	This required field is always the static string chargeclassifier
Key	string		key	key	Your api key value is provided when your account is established

TokenResponse

This is a JSON-only object returned from a successfull call to RequestJWTToken

XML Example

Not available as XML

JSON Example

                                    
        {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBUElLZXlJRCI6IjEiLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1Q.TC-6hk_0dC2t0vgtQ8ijGQlTG-CMK6L8C_B0avNM3Kc"}

Field Name	Type	Required	XML Name	JSON Name	Comments
token	string		N/A	token	This value is attached as your `Authentication Bearer` http header

StatusResponse

The object is the result of the call to CheckStatus

XML Example

    
        <status-response>
        <status>Ready</status>
        <message>Service is ready.</message>
        </status-response>

JSON Example

    
        {"status":"Ready","message":"Service is ready."}

Field Name	Type	Required	XML Name	JSON Name	Comments
ServiceStatus	enumeration see Comments		status	status	One of the following values: Stopped Building Ready Faulted
Message	string		message	message	Describes the ServiceStatus in more detail

CategoryDetails

The object returned from a call to CategoryInfo. This object contains the statistics

XML Example

    
        <category-details>
        <timestamp>2020-03-03T15:53:21.0770524-05:00</timestamp>
        <all-statistics>
        <macro-accuracy>95.9010%</macro-accuracy>
        <micro-accuracy>97.0800%</micro-accuracy>
        <log-loss>11.3987%</log-loss>
        <log-reduction>88.2067%</log-reduction>
        </all-statistics>
        <categories />
        </category-details>

JSON Example

    
        {
        "timestamp": "2020-03-03T15:53:21.0770524-05:00",
        "allstatistics": {
        "macroaccuracy": "95.9010%",
        "microaccuracy": "97.0800%",
        "logloss": "11.3987%",
        "logreduction": "88.2067%"
        },
        "categories":[]

Field Name	Type	XML Name	JSON Name	Comments
Timestamp	Date/Time	timestamp	timestamp	Informs caller as to when the statistics were generated
AllStatistics	object see Comments	all-statistics	allstatistics	This object is a weighted average of all the categories' combined statistics. The following statistics are included: macro accuracy micro accuracy log loss log loss reduction All statistics are represented as percentages to 4 decimal places
Categories	Array of CategoryDetail	categories	categories	This array of CategoryDetail objects contains every distinct category the learning machine uses

CategoryDetail

The individual statistics and training information for a specific category.

XML Example

    
        <category-detail>
        <category-id>80</category-id>
        <name>Homicide Offenses</name>
        <crime-against>
        <attribute>Person</attribute>
        </crime-against>
        <train-count>142</train-count>
        <status>Ready</status>
        <training-started>2020-03-02T14:49:52.6852168-05:00</training-started>
        <training-finished>2020-03-02T14:50:16.3838342-05:00</training-finished>
        <statistics>
        <macro-accuracy>97.0674%</macro-accuracy>
        <micro-accuracy>97.8982%</micro-accuracy>
        <log-loss>6.6123%</log-loss>
        <log-reduction>90.9055%</log-reduction>
        </statistics>
        </category-detail>

JSON Example

    
        {
        "categoryid": 80,
        "name": "Homicide Offenses",
        "crimeagainst": ["Person"],
        "traincount": 142,
        "status": "Ready",
        "trainingstarted": "2020-03-02T14:49:52.6852168-05:00",
        "trainingfinished": "2020-03-02T14:50:16.3838342-05:00",
        "statistics": {
        "macroaccuracy": "97.0674%",
        "microaccuracy": "97.8982%",
        "logloss": "6.6123%",
        "logreduction": "90.9055%"
        }
        }

Field Name	Type	XML Name	JSON Name	Comments
CategoryId	integer	category-id	categoryid	This id can be used to select a specific category to include when calling the Criminal API method
CategoryName	integer	name	name	This name can be used to select a specific category to include when calling the Criminal API method
CrimeAgainst	array of enumeration	crime-against	crimeagainst	An array of one or more values: Community JusticeSystem Person Property Society Unknown
TrainingCount	integer	train-count	traincount	The number of distinct, trained corpus charges that have been classified
Status	enumeration see Comments	status	status	The status of this category. One of the following values: Stopped Building Ready Faulted
TrainingStart	Date/Time	training-started	trainingstarted	The time the model training for this category started
TrainingFinish	Date/Time	training-finished	trainingfinished	The time the model training for this category finished
Statistics	object see Comments	statistics	statistics	This object is the category's statistics as calculated by the last training run. The following statistics are included: macro accuracy micro accuracy log loss log loss reduction All statistics are represented as percentages to 4 decimal places

TrainingRequest

The list of text strings to be trained and incorporated into the machine learning model.

XML Example

    
        <training-request>
        <charges>
        <charge>Drunk in public</charge>
        <charge>Panhandling without a license</charge>
        <charge>Hunting game out of season</charge>
        </charges>
        </training-request>

JSON Example

    
        {
        "charges": [
        "Drunk in public",
        "Panhandling without a license",
        "Hunting game out of season"
        ]
        }

Field Name	Type	Required	XML Name	JSON Name	Comments
Charges	Array of string		charges	charges	The array is unbounded but the amount of charges that will be accepted for processing is based on the number of requests performed in a 30 day period.

TrainingResponse

The response returned back to the caller when calling TrainingRequest

XML Example

    
        <training-response>
        <items>
        <item>
        <status>AlreadyQueued</status>
        <timestamp>2020-03-05T08:29:33.1158903-05:00</timestamp>
        <charge-text>Drunk in public</charge-text>
        </item>
        <item>
        <status>Accepted</status>
        <timestamp>2020-03-05T08:29:33.1158903-05:00</timestamp>
        <charge-text>Panhandling without a license</charge-text>
        </item>
        <item>
        <status>OverLimit</status>
        <timestamp>2020-03-05T08:29:33.1158903-05:00</timestamp>
        <charge-text>Hunting game out of season</charge-text>
        </item>
        </items>
        </training-response>

JSON Example

    
        {
        "items": [
        {
        "status": "AlreadyQueued",
        "timestamp": "2020-03-05T08:29:33.1158903-05:00",
        "chargetext": "Drunk in public"
        },
        {
        "status": "Accepted",
        "timestamp": "2020-03-05T08:29:33.1158903-05:00",
        "chargetext": "Panhandling without a license"
        },
        {
        "status": "OverLimit",
        "timestamp": "2020-03-05T08:29:33.1158903-05:00",
        "chargetext": "Hunting game out of season"
        }
        ]
        }

Field Name	Type	Required	XML Name	JSON Name	Comments
Items	Array of TrainingItem		items	items	For each item submitted in a TrainingRequest, the caller will receive one TrainingItem back in this array

TrainingItem

The object that is returned to the caller as response to a TrainingRequest. This informs the user about the status of the training request item(s).

XML Example

    
        <training-item>
        <status>AlreadyQueued</status>
        <timestamp>2020-03-05T08:40:08.8815843-05:00</timestamp>
        <charge-text>Drunk in public</charge-text>
        </training-item>

JSON Example

    
        {
        "status": "Accepted",
        "timestamp": "2020-03-05T08:29:33.1158903-05:00",
        "chargetext": "Panhandling without a license"
        }

Field Name	Type	XML Name	JSON Name	Comments
Status	enumeration see Comments	status	status	Informs the caller about the status of the training request item. One of the following values: Accepted - The item is accepted for training and will be trained at a later time AlreadyQueued - The item is already pending in the training queue. OverLimit - There are no free training requests available for the caller's account
Timestamp	Date/Time	timestamp	timestamp	The time when the training item was responded to by the system
ChargeText	string	charge-text	chargetext	The is the echo of the text submitted for training in the TrainingRequest

ClassifierRequest

This object is the caller request to classify a term.

XML Example

    
        <request>
        <source-text>Failure to yield - accident</source-text>
        <client-reference>558886868</client-reference>
        <required-confidence>0.9</required-confidence>
        <options>
        <stop-words>
        <word>walk</word>
        <word>then</word>
        <word>or</word>
        </stop-words>
        </options>
        </request>

JSON Example

    
        {
        "sourcetext": "Failure to yield - accident",
        "clientreference": "558886868",
        "requiredconfidence": 0.9,
        "options": {
        "customstopwords": [
        "walk",
        "then",
        "or"
        ]
        },
        "categoriestoevaluate": null,
        "crimeagainst": null
        }

Field Name	Type	XML Name	JSON Name	Comments
SourceText	string	source-text	sourcetext	This is the term to be classified. Cannot be null or empty
ClientReference	string	client-reference	clientreference	This is an echo field that can be used to associate a result from the caller's prospective
RequiredConfidence	number/decimal	required-confidence	requiredconfidence	The minimum percentage value a category must match to be considered a classification. NOTE: If unset, the confidence level defaults to .95
CategoriesToEvaluate	Array of int	categories-to-evaluate	categoriestoevaluate	If you wish to limit the list of categories to be evaulated, you can pass their category-ids here. *NOTE: See the CategoryInfo* method to find these ID values.** If not provided, the classifier will apply ALL categories
CrimeAgainst	Array of enumeration	crime-against	crimeagainst	If you wish to limit the list of categories to be evaulated to a specific crime victim (EX: 'property' or 'person'), you can pass in a list of victims to be evaluated. *NOTE: See the CategoryInfo* method to find these enumeration values.** If not provided, the classifier will apply ALL crime victims.
Options	object see ClassifierOptions	options	options	This object contains any options available when requesting a classification.

ClassiferOptions

Additional parameters to pass to a Classifier Request

XML Example

    
        <classifier-options>
        <stop-words>
        <word>walk</word>
        <word>then</word>
        <word>or</word>
        </stop-words>
        </classifier-options>

JSON Example

    
        {
        "customstopwords": [
        "walk",
        "then",
        "or"
        ]
        }

Field Name	Type	Required	XML Name	JSON Name	Comments
CustomStopWords	Array of string		stop-words	customstopwords	You can add additional stop words to be evaulated when submitting a classification. This will ADD to the stop word list. *NOTE: See the GetStopWords* method to find current stop words being used by the classifier.** If not provided, the classifier will apply the default stop word list.

Downloads and Samples

You can use the examples below to see complete requests and responses for many of the service methods.
NOTE: You will need to call RequestJWTToken to obtain a valid JSON Web Token and then attach it to your request's Authentication Bearer header for the API example calls to succeed.

File name	Format	Description
Classification Request	Fiddler HTTP Request	This file is a raw http request to the 'Criminal' classification method
Classification Response	JSON	The JSON results of a call to the 'Criminal' method
JWT Request	Fiddler HTTP Request	'RequestJWTToken' method call request
CategoryInfo Response	XML	Example 'CategoryStatistics' object returned as method call response