Working with Taxonomies

Taxonomies in WordPress are a means of classifying content. Out of the box, WordPress has two primary taxonomies, categories (category) and tags (post_tag). Plugins and themes can specify additional custom taxonomies.

Taxonomies

To retrieve a list of taxonomies for a WordPress blog, use wordpress_xmlrpc.methods.taxonomies.GetTaxonomies:

from wordpress_xmlrpc import Client
from wordpress_xmlrpc.methods import taxonomies

client = Client(...)
taxes = client.call(taxonomies.GetTaxonomies())
# taxes == [WordPressTaxonomy, WordPressTaxonomy, ...]

An individual taxonomy can be retrieved by name:

category_tax = client.call(taxonomies.GetTaxonomy('category'))

Note

Taxonomies can only be created and modified within WordPress using hooks in plugins or themes. The XML-RPC API permits only reading of taxonomy metadata.

Terms

Terms are the individual entries in a taxonomy.

For example, to retrieve all blog categories:

categories = client.call(taxonomies.GetTerms('category'))

And to create a new tag:

from wordpress_xmlrpc import WordPressTerm

tag = WordPressTerm()
tag.taxonomy = 'post_tag'
tag.name = 'My New Tag'
tag.id = client.call(taxonomies.NewTerm(tag))

Or to create a child category:

parent_cat = client.call(taxonomies.GetTerm('category', 3))

child_cat = WordPressTerm()
child_cat.taxonomy = 'category'
child_cat.parent = parent_cat.id
child_cat.name = 'My Child Category'
child_cat.id = client.call(taxonomies.NewTerm(child_cat))

Terms and Posts

Terms are of little use on their own, they must actually be assigned to posts.

If you already have WordPressTerm objects, use terms property of WordPressPost:

tags = client.call(taxonomies.GetTerms('post_tag', {...}))

post = WordPressPost()
post.title = 'Post with Tags'
post.content = '...'
post.terms = tags
post.id = client.call(posts.NewPost(post))

If you want to add a category to an existing post:

category = client.call(taxonomies.GetTerm('category', 3))
post = client.call(posts.GetPost(5))

post.terms.append(category)
client.call(posts.EditPost(post.id, post))

But what if you have not yet retrieved the terms or want to create new terms? For that, you can use the terms_names property of WordPressPost:

post = WordPressPost()
post.title = 'Post with new tags'
post.content = '...'
post.terms_names = {
        'post_tag': ['tagA', 'another tag'],
        'category': ['My Child Category'],
}
post.id = client.call(posts.NewPost(post))

Note that terms_names is a dictionary with taxonomy names as keys and list of strings as values. WordPress will look for existing terms with these names or else create new ones. Be careful with hierarchical taxonomies like category because of potential name ambiguities (multiple terms can have the same name if they have different parents); if WordPress detects ambiguity, it will throw an error and ask that you use terms instead with a proper WordPressTerm.

Advanced Querying

By Count

To find the 20 most-used tags:

tags = client.call(taxonomies.GetTerms('post_tag', {'number': 20, 'orderby': 'count', 'order': 'DESC'}))

for tag in tags:
        print tag.name, tag.count

Searching/Autocomplete

To perform case-insensitive searching against term names, use the search option for filter:

user_input = 'wor'  # e.g., from UI textbox
tags = client.call(taxonomies.GetTerms('post_tag', {'search': user_input, 'orderby': 'count', 'number': 5}))

suggestions = [tag.name for tag in tags]
# suggestions == ['word', 'WordPress', 'world']