End of life

As of December 31st, 2011,Taxonomy Builder API has reached “end of life” and is deprecated in favor of Taxonomy CSV import/export. Please post an issue if you feel this module is still valuable and wish to pick up maintainership.


The example below creates a simple hierarchy of countries, states, and cties.

  // Replace with whatever vocabulary ID the terms should be added to.
  $vid = 12;

  // Hierarchy arrays.
  $hierarchies = array(
    array('United states', 'Massachusetts', 'Boston'),
    array('United states', 'Massachusetts', 'Worcester'),
    array('United states', 'New York', 'New York'),
    array('United states', 'New York', 'Albany'),

  // Adds terms to the taxonomy hierarchy one by one.  This makes it easy to
  // break up large trees via the batch API so the build doesn't time out.
  foreach ($hierarchies as $hierarchy) {
    taxonomy_builder_save_terms($vid, $hierarchy);

This produces a taxonomy tree with the following structure:

  • United states
    • Massachusetts
      • Boston
      • Worcester
    • New York
      • New York
      • Albany

The example below adds a hierarchy of terms with descriptions to the tree. Any array key accepted by the taxonomy_save_term() function is valid.

  // Array of $form_value arrays that will be passed to taxonomy_save_term().
  $hierarchy = array(
      'name' => 'United States',
      'description' => 'Country',
      'name' => 'Massachusetts',
      'description' => 'State',
      'name' => 'Boston',
      'description' => 'City',

  // Adds terms to the tree.
  taxonomy_builder_save_terms($vid, $hierarchy);

The example below batch imports terms in CSV files 1000 lines per batch operation.

  // Builds and executes batch process, returns to homepage when finished.
  $batch = taxonomy_builder_get_batch($vid, array('test1.csv', 'test2.csv'), 1000);

Other modules can interact with Taxonomy Builder API via the hook_taxonomy_builder_term_alter() and hook_taxonomy_builder_term_save() hooks, although hook_taxonomy() will probably be suitable in most cases. Visit the taxonomy_builder.api.php file for more detailed information.

Project Information