WordPress.org

Codex

XML-RPC WordPress API/Taxonomies

These XML-RPC methods are for interacting with taxonomies and terms.

To retrieve or change the terms assigned to a post, see the terms field in wp.getPost, wp.newPost, and wp.editPost.

Contents

wp.getTaxonomy

Retrieve information about a taxonomy.

Note: This method does not return the terms in the taxonomy. See #wp.getTerms.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • string taxonomy

Return Values

  • struct: See get_taxonomy.
    • string name
    • string label
    • bool hierarchical
    • bool public
    • bool show_ui
    • bool _builtin
    • struct labels1
    • struct cap2
    • array object_type3

1 labels meta-field
2 cap meta-field.
3 object_type meta-field.


Errors

  • 401
    • If the user does not have the assign_terms cap for this taxonomy.
  • 403
    • If invalid taxonomy name is specified.

Filters

xmlrpc_prepare_taxonomy

Immediately before returning the prepared taxonomy data, the value is passed through the xmlrpc_prepare_taxonomy filter. The filter has two parameters:

  1. The prepared taxonomy data about to be returned
  2. The original taxonomy data array, see get_taxonomy.

wp.getTaxonomies

Retrieve a list of taxonomies.

Parameters

  • int blog_id
  • string username
  • string password

Return Values

Notes

  • Response will only contain taxonomies where the user has the assign_terms cap.

Filters

Supports same filters as #wp.getTaxonomy.

wp.getTerm

Retrieve a taxonomy term.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • string taxonomy
  • int term_id

Return Values

  • struct: See get_term.
    • string term_id
    • string name
    • string slug
    • string term_group
    • string term_taxonomy_id
    • string taxonomy
    • string description
    • string parent
    • int count

Errors

  • 401
    • If the user does not have the assign_terms cap for this taxonomy.
  • 403
    • If invalid taxonomy name is specified.
  • 404
    • If no term with that term_id exists.

Filters

xmlrpc_prepare_term

Immediately before returning the prepared term data, the value is passed through the xmlrpc_prepare_term filter. The filter has two parameters:

  1. The prepared term data about to be returned
  2. The original term data array, see get_term.

wp.getTerms

Retrieve list of terms in a taxonomy.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • string taxonomy
  • struct filter: Optional.
    • int number
    • int offset
    • string orderby
    • string order
    • bool hide_empty: Whether to return terms with count=0.
    • string search: Restrict to terms with names that contain (case-insensitive) this value.

Return Values

Errors

  • 401
    • If the user does not have the assign_terms cap for this taxonomy.
  • 403
    • If invalid taxonomy name is specified.

Filters

Supports same filters as #wp.getTerm.

wp.newTerm

Create a new taxonomy term.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • struct content
    • string name
    • string taxonomy
    • string slug: Optional.
    • string description: Optional.
    • int parent: Optional.

Return Values

  • string term_id

Errors

  • 401
    • If the user does not have the manage_terms cap for this taxonomy.
  • 403
    • If invalid taxonomy name is specified.
    • If the term name is empty.
    • If parent is set but the taxonomy is not hierarchical.
    • If no term with that parent ID exists.

wp.editTerm

Edit an existing taxonomy term.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • int term_id
  • struct content
    • string taxonomy
    • string name: Optional.
    • string slug: Optional.
    • string description: Optional.
    • int parent: Optional.

Return Values

  • bool true

Errors

  • 401
    • If the user does not have the edit_terms cap for this taxonomy.
  • 403
    • If invalid taxonomy name is specified.
    • If the term name is empty.
    • If parent is set but the taxonomy is not hierarchical.
    • If no term with that parent ID exists.
  • 404
    • If no term with that term_id ID exists.

wp.deleteTerm

Delete an existing taxonomy term.

Added in WordPress 3.4.

Parameters

  • int blog_id
  • string username
  • string password
  • string taxonomy
  • int term_id

Return Values

  • bool true

Errors

  • 403
    • If invalid taxonomy name is specified.
    • If the user does not have the delete_terms cap for this taxonomy.
  • 404
    • If no term with that term_id ID exists.