Taxonomies

A taxonomy is a way of grouping things together. If you've ever dealt with WordPress, you'll be familiar with its two main taxonomies: categories and tags. They are both independent ways to group together or sub-divide the same content.

Inside a taxonomy you have a number of terms. In WordPress, this would be the actual tag or category name that you might then assign to a post.

With Nymbol, you can create a taxonomy as simple as "Category", or you can get more advanced. In the PubCrawl example, we have two different taxonomies: Category and Crawl. The Category example is fairly self-explanatory, but Crawl allows us to create different pub crawls - or in the future, allow users to create their own. They're not objects in their own right, but ways of categorising and ordering objects. Each crawl is represented by a taxonomy term, and we can attach each term to one or many objects, and each object can have many terms from many taxonomies attached to it.

Oh confused would we? Let's look at some code.

Listing taxonomies

Taxonomies are bound to collections. You can have as many taxonomies as you need, but they don't exist across different collections, so if that's something you need, you might want to consider using subcollections.

To list taxonomies for a given collection, you'd perform the following API call:

GET /api/manager/collection/<collection_id>/taxonomies.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

The response will look something like this:

[
    {
        "name": "Categories",
        "ordering_name": "categories",
        "collection": 3,
        "uid": "laILMg3",
        "id": 3,
        "assets": 125
    },
    {
        "name": "Crawls",
        "ordering_name": "crawls",
        "collection": 3,
        "uid": "AkyxMuH",
        "id": 4,
        "assets": 72
    }
]

You should find these objects fairly self-explanatory. Like the call to /api/manager/collection.json, you probably won't have much call for this; it exists mainly as a root to the following call.

Listing terms

You can list the terms inside a given taxonomy by passing the collection ID and the taxonomy ID to the following API function:

GET /api/manager/collection/<collection_id>/taxonomies/<taxonomy_id>/terms.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

You'll get a response similar to this:

[
    {
        "status": 1,
        "name": "Featured",
        "ordering_name": "featured",
        "taxonomy": 5,
        "description": "",
        "id": 1,
        "uid": "lNyfS6o"
    }
]

Like with assets and resources, taxonomy terms can have descriptions which can be made available in any language. See the Setting the language section of the Assets guide for details on how to request content in your device's language (providing it's been added in that language by the content curator).

Assets attached to a term

Once you've got a taxonomy term, the next thing you'll want to do is list the assets that are associated with that term. Now here's where we break out of the usual URL structure, and revert back to /api/manage/collection/x/assets.json.

In the Assets guide we looked at how to list assets in a collection or subcollection. You would use the same API call to retrieve assets from a given collection or subcollection, but tack on the following querystring parameter for each taxonomy:

?taxonomy[<tax_id>]=<term_id>

So given the example above, if we wanted to list all featured pubs in Birmingham, we'd perform a query like this:

GET /api/manager/collection/<collection_id>/subcollections/<subcollection_id>/assets.json?taxonomy[5]=1
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

That would return the same structured output as you see in the Assets guide.

You can chain those taxonomy querystring parameters together, just changing the number in the square bracket to the taxonomy ID, and the number after the = sign to the term ID. And of course you can still order by proximity, get thumbnails and search.

Next guide: User-contributed content → ← Previous guide