This project is not covered by Drupal’s security advisory policy.

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