Using the main API

In addition to the GraphQL API previously shown, there are also several endpoints under the HTTP path /v1/taxonomy/main. This tutorial will show you how you can access them from Python.

Let's start with some imports and definitions:

import json
import requests
import pprint
pp = pprint.PrettyPrinter(width=41, compact=True)
host = "https://taxonomy.api.jobtechdev.se"

We will start by quering the versions:

version_data = requests.get(host + "/v1/taxonomy/main/versions").json()
version_data.sort(key=lambda x: x["taxonomy/timestamp"])

def disp_version(v):
    version = v["taxonomy/version"]
    timestamp = v["taxonomy/timestamp"]
    print(f"Version {version} published at {timestamp}")

print("First version:")
disp_version(version_data[0])

print("Last version:")
disp_version(version_data[-1])

version_ids = [v["taxonomy/version"] for v in version_data]

print("Version ids:")
pp.pprint(version_ids)

Output:

First version:
Version 1 published at 2021-03-05T13:38:02.440Z
Last version:
Version 22 published at 2024-02-21T16:16:00.195Z
Version ids:
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
 13, 14, 15, 16, 17, 18, 19, 20, 21, 22]

There is also a /v1/taxonomy/main/concepts endpoint. Let's look at one of the concepts from that endpoint. We put the limit parameter to one.

Many endpoints accept a version parameter to specify a version and if it is omitted, the endpoint will default to delivering data from the latest version. In the following example, we omit the version parameter:

concepts = requests.get(host + "/v1/taxonomy/main/concepts",
                        params={"limit": 1}).json()
pp.pprint(concepts)

Output:

[{'taxonomy/alternative-labels': ['Fysisk '
                                  'planerare',
                                  'Planeringsarkitekt'],
  'taxonomy/definition': 'Planeringsarkitekt/Fysisk '
                         'planerare',
  'taxonomy/id': 'ghs4_JXU_BYt',
  'taxonomy/preferred-label': 'Planeringsarkitekt/Fysisk '
                              'planerare',
  'taxonomy/type': 'occupation-name'}]

We can also pick out exactly one concept at a specific version:

concept_id = concepts[0]["taxonomy/id"]
latest_version_id = version_ids[-1]

concept = requests.get(host + "/v1/taxonomy/main/concepts",
                       params={"id": concept_id, "version": latest_version_id}).json()

pp.pprint(concept)

Output:

[{'taxonomy/alternative-labels': ['Fysisk '
                                  'planerare',
                                  'Planeringsarkitekt'],
  'taxonomy/definition': 'Planeringsarkitekt/Fysisk '
                         'planerare',
  'taxonomy/id': 'ghs4_JXU_BYt',
  'taxonomy/preferred-label': 'Planeringsarkitekt/Fysisk '
                              'planerare',
  'taxonomy/type': 'occupation-name'}]

We can list all the types. By default

types_data = requests.get(host + "/v1/taxonomy/main/concept/types",
                          params={"version": latest_version_id}).json()

print("The first 5 types:")
pp.pprint(types_data[0:5])

Output:

The first 5 types:
['barometer-occupation', 'continent',
 'country', 'driving-licence',
 'employment-duration']

That's it. We have now seen some of the most useful endpoints of the main taxonomy API.