Synonyms

---

Same entities can sometimes come in different forms. E.g. New Delhi and Delhi, New Your City and NYC. Cases where you are performing an action based on the entity value, you will have to make them homogeneous. That means, you would want your NLU model to return a single value (Delhi) for both New Delhi and Delhi. This can be done using synonyms.

Prerequisites

Make sure to log in using API and have your authorization token in a variable called AUTHORIZATION_TOKEN before running this API.

Create a Synonym Entity

Using this API you can create a synonym entity and add different variations of the synonym to it. When entities extracted by the other extractors match these variants, the entity value get transformed to the name of the synonym entity.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entity":"it services",
    "examples":[
        "it support",
        "itis",
        "ITIS",
        "IT Service"
    ],
    "language":"en",
    "entityType":"synonym"
}'

Attribute	Required	Type	Limits	Description
entity	true	str	30 characters	Name of the entity that you are creating
examples	true	list		A list of regular expressions as string.
language	true	str		one of the supported languages
entityType	true	str	One of lookup, regex, synonym	The type of entity this is.

Here it support, itis, IT Service, ITIS are all considered synonyms of it services. That means when entity extractors will extract any of these the value will be changed to it services

List Synonym Entities

Use our API to access all available lookup entities.

Filter by entity type

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/list/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw "{
    \"filter\":{
        \"entityType\":\"synonym\"
    },
    \"search\": \"\",
    \"pageNumber\": 1,
    \"pageSize\": 10
}"

You can filter all entities by passing an entityType attribute in the filter. This is a pagination API, hence, pageSize determines how many projects to retrieve and pageNumber determines which page to fetch.

Filter by language

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/list/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw "{
    \"filter\":{
        \"entityType\":\"synonym\",
        \"language\":\"en\"
    },
    \"search\": \"\",
    \"pageNumber\": 1,
    \"pageSize\": 10
}"

This will show all pre-trained entities in Hindi (en)

Add Examples to a Synonym Entity

To add an example to an existing entity you will need the entityId of that entity. In this case lets add another variant called it administration.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/add/examples/entity' \
--header 'Accept: application/json, text/plain, */*' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID",
    "examples": ["it administartion"]
}'

note

While updating an existing synonym you can add multiple examples at once.

Delete Examples from a Synonym Entity

To delete an example from an existing entity you will also need the entityId of that entity. In this case lets delete the it administartion we added in the previous section.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/remove/examples/entity' \
--header 'Accept: application/json, text/plain, */*' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID",
    "examples": ["it administartion"]
}'

note

You can delete multiple examples at once. Add all examples you want to delete in the list attribute examples to do so.

Delete Synonym Entity

Using this API you can delete a lookup entity. You will need the entityId for this.

curl --location --request DELETE 'https://platform.neuralspace.ai/api/nlu/v1/entity' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityId":"YOUR-ENTITY-ID"
}'

warning

Once deleted an entity cannot be recovered.

Add Synonym Entities in NLU Projects

For every language in a project you can add synonym entities by using this API. Synonyms are added at a project level as they apply to all other entities.

curl --location --request POST 'https://platform.neuralspace.ai/api/nlu/v1/project/add/synonym' \
--header "authorization: ${AUTHORIZATION_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "projectId": "YOUR-PROJECT-ID",
    "language": "LANGUAGE-IN-PROJECT",
    "entityId":"YOUR_ENTITY-ID"
}'

Refer to the Postman collection for other APIs related to synonyms.