Get information about taxonomies
List of available taxonomies
The API provides a self-documentation resource to programmatically discover available taxonomies and their features. It has this path:
taxonomies
Therefore, the complete URL is:
https://nlapi.expert.ai/v2/taxonomies
It must be requested with the GET
method.
It returns the list of available taxonomies along with the supported languages.
In the reference section of this manual you will find all the information you need to get taxonomies information using the API's RESTful interface, specifically:
- How to build the resource path and the full endpoint
- The output format
Note
Even if you consume the API through a ready-to-use client that hides low-level requests and responses, knowing the output format helps you understand and navigate the results.
Here is an example of getting taxonomies information:
This example code uses expertai-nlapi, the open-source Python client corresponding to the nlapi-python GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the list of taxonomies with the language they support.
from expertai.nlapi.cloud.client import ExpertAiClient
client = ExpertAiClient()
output = client.taxonomies()
print("Available taxonomies:")
for taxonomy in output.taxonomies:
print(taxonomy.name)
print("\tLanguages:")
for language in taxonomy.languages:
print("\t", language.code)
This example code uses @expertai/nlapi, the open-source NodeJS client corresponding to the nlapi-nodejs GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the list of taxonomies with the language they support.
import {NLClient} from "@expertai/nlapi";
var nlClient = new NLClient();
nlClient.taxonomies().then((result) => {
console.log("Available taxonomies:");
for (const taxonomy of result.taxonomies) {
console.log(taxonomy.name)
console.log("\tLanguages:")
for (const language of taxonomy.languages) {
console.log("\t\t" + language.code);
}
}
})
This example code uses nlapi-java-sdk, the open-source Java client corresponding to the nlapi-java GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the JSON response.
import ai.expert.nlapi.security.Authentication;
import ai.expert.nlapi.security.Authenticator;
import ai.expert.nlapi.security.BasicAuthenticator;
import ai.expert.nlapi.security.DefaultCredentialsProvider;
import ai.expert.nlapi.v2.API;
import ai.expert.nlapi.v2.cloud.InfoAPI;
import ai.expert.nlapi.v2.cloud.InfoAPIConfig;
import ai.expert.nlapi.v2.message.TaxonomiesResponse;
public class Main {
public static Authentication createAuthentication() throws Exception {
DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider();
Authenticator authenticator = new BasicAuthenticator(credentialsProvider);
return new Authentication(authenticator);
}
public static void main(String[] args) {
try {
InfoAPI infoAPI = new InfoAPI(InfoAPIConfig.builder()
.withAuthentication(createAuthentication())
.withVersion(API.Versions.V2)
.build());
TaxonomiesResponse taxonomies = infoAPI.getTaxonomies();
taxonomies.prettyPrint();
}
catch(Exception ex) {
ex.printStackTrace();
}
}
}
The following curl command gets the taxonomies documentation resource of the API's REST interface.
Run the command from a shell after replacing token
with the actual authorization token.
curl -X GET https://nlapi.expert.ai/v2/taxonomies \
-H 'Authorization: Bearer token'
The server returns a JSON object.
The following curl command gets the taxonomies documentation resource of the API's REST interface.
Open a command prompt in the folder where you installed curl and run the command after replacing token
with the actual authorization token.
curl -X GET https://nlapi.expert.ai/v2/taxonomies -H "Authorization: Bearer token"
The server returns a JSON object.
Category tree
The API also provides self-documentation resources that return the category tree for a given taxonomy-language combination.
These resources have paths like this:
taxonomies/taxonomy name/language code
Boxed parts are placeholders, so for example:
https://nlapi.expert.ai/v2/taxonomies/iptc/en
is the URL of the resource returning the category tree for the iptc
taxonomy for the English language.
These resources must be requested with the GET
method.
In the reference section of this manual you will find all the information you need to get these resources using the API's RESTful interface, specifically:
- How to build resources' paths and full endpoints
- The output format
Note
Even if you consume the API through a ready-to-use client that hides low-level requests and responses, knowing the output format helps you understand and navigate the results.
For example, here is how to get the category tree of the geotax
taxonomy for English:
This example code uses expertai-nlapi, the open-source Python client corresponding to the nlapi-python GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the category tree of the geotax
taxonomy.
from expertai.nlapi.cloud.client import ExpertAiClient
def printCategory(level, category):
tabs = "\t" * level
print(tabs, category.id, category.label)
for nestedCategory in category.categories:
printCategory(level + 1, nestedCategory)
client = ExpertAiClient()
taxonomy='geotax'
language='en'
output = client.taxonomy(params={'taxonomy': taxonomy, 'language': language})
print("geotax categories' tree:")
for category in output.taxonomy[0].categories:
printCategory(0, category)
This example code uses @expertai/nlapi, the open-source NodeJS client corresponding to the nlapi-nodejs GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the category tree of the geotax
taxonomy.
import {NLClient} from "@expertai/nlapi";
import {Language} from "@expertai/nlapi";
function printCategory(level, category) {
const tabs = "\t".repeat(level);
console.log(tabs + category.id, category.label);
if (category.categories) {
for (const nestedCategory of category.categories) {
printCategory(level + 1, nestedCategory)
}
}
}
var nlClient = new NLClient();
nlClient.taxonomy({
taxonomy: "geotax",
language: Language.EN
}).then((result) => {
console.log("geotax categories' tree:");
for (const category of result.data[0].taxonomy[0].categories) {
printCategory(0, category)
}
})
This example code uses nlapi-java-sdk, the open-source Java client corresponding to the nlapi-java GitHub project.
The client gets user credentials from two environment variables:
EAI_USERNAME
EAI_PASSWORD
Set those variables with your account credentials before running the sample program below.
The program prints the JSON response.
import ai.expert.nlapi.security.Authentication;
import ai.expert.nlapi.security.Authenticator;
import ai.expert.nlapi.security.BasicAuthenticator;
import ai.expert.nlapi.security.DefaultCredentialsProvider;
import ai.expert.nlapi.v2.API;
import ai.expert.nlapi.v2.cloud.InfoAPI;
import ai.expert.nlapi.v2.cloud.InfoAPIConfig;
import ai.expert.nlapi.v2.message.TaxonomyResponse;
public class Main {
public static Authentication createAuthentication() throws Exception {
DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider();
Authenticator authenticator = new BasicAuthenticator(credentialsProvider);
return new Authentication(authenticator);
}
public static void main(String[] args) {
try {
InfoAPI infoAPI = new InfoAPI(InfoAPIConfig.builder()
.withAuthentication(createAuthentication())
.withVersion(API.Versions.V2)
.build());
TaxonomyResponse taxonomy = infoAPI.getTaxonomy("geotax", API.Languages.en);
taxonomy.prettyPrint();
}
catch(Exception ex) {
ex.printStackTrace();
}
}
}
The following curl command gets the resource of the API's REST interface that returns the categories' tree of the English geotax
taxonomy.
Run the command from a shell after replacing token
with the actual authorization token.
curl -X GET https://nlapi.expert.ai/v2/taxonomies/geotax/en \
-H 'Authorization: Bearer token'
The server returns a JSON object.
The following curl command gets the resource of the API's REST interface that returns the categories' tree of the English geotax
taxonomy.
Open a command prompt in the folder where you installed curl and run the command after replacing token
with the actual authorization token.
curl -X GET https://nlapi.expert.ai/v2/geotax/en -H "Authorization: Bearer token"
The server returns a JSON object.