Sitemap API

The Sitemap API returns the pages that would be included in the sitemap.xml file so that you can build out your own custom sitemap page.

The Sitemap API is available on BranchCMS Basic or higher plans.

Learn more about APIs.

The return value from the API call will always be an array of pages. Because of that, you will almost always assign the API result to a variable.

The pages that are returned include any regular pages and app pages that are configured to be included in the sitemap.

There are three things you can do with the Sitemap API.

Get all pages and app pages
Get only the pages within an app
Get only a section within an app

Get all pages and app pages

The default output from the API call is an array of any regular pages and app pages that are configured to be included in the sitemap.

App pages are organized by app section.

{% set sitemap = _api.sitemap.get() %}

Below is an example showing how the sitemap data is organized.

Get only the pages within an app

If you're building a sitemap page you may want to display apps like the blog or calendar separate from regular pages. You can filter the pages returned from the API to only get the pages for a specific app. To do so you would pass the app instance key to the get() method.

For example:

{% set blogPages = _api.sitemap.get('blog') %}

If your app has one or more instances you can go to the "Instances" section of the app to get the available app keys.

If your app doesn't have multiple instances then most likely the default app key is the app instance key. Below is the list of default app keys that could be used if you haven't customized the instance key for the app.

app
blog
calendar
campaign
directory
document
employment
gallery
members
page
realestate
rental
store
trails

If you are wanting to only get regular pages you can use the sitemap pages API, or you can do the following.

{% set pages = _api.sitemap.get('page') %}

Get only a section within an app

In addition to filtering pages by an app, you can also filter to specific sections within an app.

To do so you will pass the app to the get() parameter and you will need to pass the app section to the section() parameter.

Below is an example to get only the posts within the blog app.

{% set blogPosts = _api.sitemap.get('blog').section('posts') %}

The result from using section() is usually an array of pages. The exception is for app sections where there is only one page.

The app sections that have only one page include:

home
categorylist
taglist
Any other "list" page for the app like "itemlist"

For those types of pages the result is the page data instead of an array of pages.

{% set blogHome = _api.sitemap.get('blog').section('home') %}

<p><a href="{{ blogHome.url }}">Blog Home</a></p>

Instead of using section(), you can use the name of the app section as the last parameter.

For example, you're wanting to get the app home page you can use the home() parameter.

Or, if you're wanting to get the post list page you can use the postList() parameter.

Note that the parameter name does not need to be all lowercase. postlist() works as does postList().

{% set blogHome = _api.sitemap.get('blog').home() %}

Below are common sections within apps. Note, they are not in all apps, but they are common to most.

home - the app home page
categories - the individual category pages
categorylist - the category list page
taglist - the tags list page
tags - the individual tag pages

Below is a list of the available apps and the sections within that app.

App

categories
categorylist
home
itemlist - the item list page
items - the individual app item pages
taglist
tags

These examples assume that the app instance key is "app". Yours may be different.

{% set categories = _api.sitemap.get('app').categories() %}
{% set categoryList = _api.sitemap.get('app').categoryList() %}
{% set home = _api.sitemap.get('app').home() %}
{% set itemList = _api.sitemap.get('app').itemList() %}
{% set items = _api.sitemap.get('app').items() %}
{% set tagList = _api.sitemap.get('app').tagList() %}
{% set tags = _api.sitemap.get('app').tags() %}

Blog

categories
categorylist
home
postlist - the post list pages
posts - the individual post pages
taglist
tags

These examples assume that the app instance key is "blog". Yours may be different.

{% set categories = _api.sitemap.get('blog').categories() %}
{% set categoryList = _api.sitemap.get('blog').categoryList() %}
{% set home = _api.sitemap.get('blog').home() %}
{% set postList = _api.sitemap.get('blog').postList() %}
{% set posts = _api.sitemap.get('blog').post() %}
{% set tagList = _api.sitemap.get('blog').tagList() %}
{% set tags = _api.sitemap.get('blog').tags() %}

Calendar

categories
categorylist
events - the individual event pages
home
taglist
tags

These examples assume that the app instance key is "calendar". Yours may be different.

{% set categories = _api.sitemap.get('calendar').categories() %}
{% set categoryList = _api.sitemap.get('calendar').categoryList() %}
{% set home = _api.sitemap.get('calendar').home() %}
{% set events = _api.sitemap.get('calendar').events() %}

Campaign

campaignlist - the campaign list page
campaigns - the individual campaign pages
categories
categorylist
home

These examples assume that the app instance key is "campaign". Yours may be different.

{% set campaigns = _api.sitemap.get('campaign').campaigns() %}
{% set categories = _api.sitemap.get('campaign').categories() %}
{% set categoryList = _api.sitemap.get('campaign').categoryList() %}
{% set home = _api.sitemap.get('campaign').home() %}

Document

categories
categorylist
documentlist - the document list pages
documents - the individual document pages
home

These examples assume that the app instance key is "document". Yours may be different.

{% set categories = _api.sitemap.get('document').categories() %}
{% set categoryList = _api.sitemap.get('document').categoryList() %}
{% set documentList = _api.sitemap.get('document').documentList() %}
{% set documents = _api.sitemap.get('document').documents() %}
{% set home = _api.sitemap.get('document').home() %}

Employment

categories
categorylist
home
jobs - the individual job pages
joblist - the job list page

These examples assume that the app instance key is "employment". Yours may be different.

{% set categories = _api.sitemap.get('employment').categories() %}
{% set categoryList = _api.sitemap.get('employment').categoryList() %}
{% set home = _api.sitemap.get('employment').home() %}
{% set jobList = _api.sitemap.get('employment').jobList() %}
{% set jobs = _api.sitemap.get('employment').jobs() %}

Gallery

categories
categorylist
home
itemlist - the item list page
items - the individual item pages
taglist
tags

These examples assume that the app instance key is "gallery". Yours may be different.

{% set categories = _api.sitemap.get('gallery').categories() %}
{% set categoryList = _api.sitemap.get('gallery').categoryList() %}
{% set home = _api.sitemap.get('gallery').home() %}
{% set itemList = _api.sitemap.get('gallery').itemList() %}
{% set items = _api.sitemap.get('gallery').items() %}
{% set tagList = _api.sitemap.get('gallery').tagList() %}
{% set tags = _api.sitemap.get('gallery').tags() %}

Members

categories
categorylist
home
profilelist - the profile list page
profiles - the individual profile pages
taglist
tags

These examples assume that the app instance key is "members". Yours may be different.

{% set categories = _api.sitemap.get('members').categories() %}
{% set categoryList = _api.sitemap.get('members').categoryList() %}
{% set home = _api.sitemap.get('members').home() %}
{% set profileList = _api.sitemap.get('members').profileList() %}
{% set profiles = _api.sitemap.get('members').profiles() %}
{% set tagList = _api.sitemap.get('members').tagList() %}
{% set tags = _api.sitemap.get('members').tags() %}

Real Estate

agentlist - the agent list page
agents - the individual agent pages
categories
categorylist
home
properties - the individual property pages
propertylist - the property list page

These examples assume that the app instance key is "realestate". Yours may be different.

{% set agentList = _api.sitemap.get('realestate').agentList() %}
{% set agents = _api.sitemap.get('realestate').agents() %}
{% set categories = _api.sitemap.get('realestate').categories() %}
{% set categoryList = _api.sitemap.get('realestate').categoryList() %}
{% set home = _api.sitemap.get('realestate').home() %}
{% set properties = _api.sitemap.get('realestate').properties() %}
{% set propertyList = _api.sitemap.get('realestate').propertyList() %}

Rental

categories
categorylist
home
properties - the individual property pages
propertylist - the property list page

These examples assume that the app instance key is "rental". Yours may be different.

{% set categories = _api.sitemap.get('rental').categories() %}
{% set categoryList = _api.sitemap.get('rental').categoryList() %}
{% set home = _api.sitemap.get('rental').home() %}
{% set properties = _api.sitemap.get('rental').properties() %}
{% set propertyList = _api.sitemap.get('rental').propertyList() %}

Storage

home
locationlist - the location list page
locations - the individual location pages
unitlist - the unit list page
units - the individual unit pages
unitgrouplist - the unit group list page
unitgroups - the individual unit group pages
unittypelist - the unit type list page
unittypes - the individual unit type pages

These examples assume that the app instance key is "storage". Yours may be different.

{% set home = _api.sitemap.get('storage').home() %}
{% set locationLIst = _api.sitemap.get('storage').locationList() %}
{% set locations = _api.sitemap.get('storage').locations() %}
{% set unitList = _api.sitemap.get('storage').unitList() %}
{% set units = _api.sitemap.get('storage').units() %}
{% set unitGroupList = _api.sitemap.get('storage').unitGroupList() %}
{% set unitGroups = _api.sitemap.get('storage').unitGroups() %}
{% set unitTypeList = _api.sitemap.get('storage').unitTypeList() %}
{% set unitTypes = _api.sitemap.get('storage').unitTypes() %}

Store

categories
category
home
manufacturerlist - the manufacturer list page
manufacturers - the individual manufacture pages
productlist - the product list page
products - the individual product pages
taglist
tags

These examples assume that the app instance key is "store". Yours may be different.

{% set categories = _api.sitemap.get('store').categories() %}
{% set categoryList = _api.sitemap.get('store').categoryList() %}
{% set home = _api.sitemap.get('store').home() %}
{% set manufacturerList = _api.sitemap.get('store').manufacturerList() %}
{% set manufacturers = _api.sitemap.get('store').manufacturers() %}
{% set productList = _api.sitemap.get('store').productList() %}
{% set products = _api.sitemap.get('store').products() %}
{% set tagList = _api.sitemap.get('members').tagList() %}
{% set tags = _api.sitemap.get('members').tags() %}

Trails

home
traillist - the trail list page
trails - the individual trail pages

These examples assume that the app instance key is "trails". Yours may be different.

{% set home = _api.sitemap.get('store').home() %}
{% set trailList = _api.sitemap.get('store').trailList() %}
{% set trails = _api.sitemap.get('store').trails() %}

Page Data

The information included for each page includes:

app - The app name.
appInstance - The app instance name.
appSection - The app section.
breadcrumb - The breadcrumb text for the page. For performance reasons this is not set on individual app items because that would typically involve parsing dynamic breadcrumb templates.
changeFrequency - The sitemap.xml change frequency value. This is only used with regular pages.
id - The id of the page or app item. Not set on the app home or app item list pages.
name - The page name or app item name. If this is a list page like a blog post list page then the name value will be the app instance name followed by what the list page contains. For example: Blog Posts, Employment Jobs, or Store Products.
priority - The sitemap.xml priority value. This is only used with regular pages.
title - The page title. For performance reasons this is not set on individual app items because that would typically involve parsing dynamic title templates.
updatedOn - The numerical timestamp of when the page or app item was last updated. Use the date filter to format the date.
url - The URL for the page or app item.

Examples

Loop through the entire sitemap data at once

Below is a basic example to simply loop through the apps in the sitemap and then output them. This probably isn't how you want to build your sitemap page, but it shows some examples of how the full sitemap data can be looped through.

{# This builds the different sections of the sitemap #}
{% macro buildSections(app) %}
    <ul>
        {% for key, section in app  %}
            <li><b>{{ key|ucfirst }}</b>
                {% import _self as macros %}
                {{ macros.buildSitemap(section) }}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{# This builds the unordered list of pages within an app section #}
{% macro buildSitemap(pages) %}
    <ul>
        {% for page in pages %}
            <li><a href="{{ page.url }}">{{ page.name }}</a> (Last updated on {{ page.updatedOn|date('F j, Y \\a\\t g:i a') }})
                {% if page.children %}
                    {% import _self as macros %}
                    {{ macros.buildSitemap(page.children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{% import _self as macros %}

{# Get the full sitemap data, loop through the apps, and output the sections and pages #}
{% set sitemap = _api.sitemap.get() %}
{% for key, app in sitemap %}
    <h2>{{ key }}</h2>
    {% if key != 'page' %}
        {{ macros.buildSections(app) }}
    {% else %}
        {{ macros.buildSitemap(app) }}
    {% endif %}
{% endfor %}

Display pages and apps separately

Below are some examples of displaying regular pages separately from app pages. For these examples we're going to use a site that has a blog with a lot of posts and the employment app with about a dozen jobs. Because there are a lot of posts we're not going to list all blog posts, but we want to list the other app pages and categories. For the employment app we're going to just list the app home page and the jobs.

There are three ways to do this.

Get the full sitemap data as a big array and then pull out the parts that we want.
Get the apps that we need as individual arrays and then pull out the parts we want.
Use the app section filters on the API to retrieve just those specific sections.

If you are retrieving app sections from the array of sitemap data instead of filtering the API, make sure that you use the lowercase version of the app section.
For example, with the API call, you can use the case insensitive version:

{% set categoryList = _api.sitemap.get('blog').categoryList() %}

But when accessing the sitemap app data you need to use the lower case version

{% set sitemap = _api.sitemap.get() %}
{{ sitemap.blog.categorylist.url }}

Get the full sitemap data as a big array and then pull out the parts that we want.

{# This builds the different sections of the sitemap #}
{% macro buildSections(app) %}
    <ul>
        {% for key, section in app  %}
            <li><b>{{ key|ucfirst }}</b>
                {% import _self as macros %}
                {{ macros.buildSitemap(section) }}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{# This builds the unordered list of pages within an app section #}
{% macro buildSitemap(pages) %}
    <ul>
        {% for page in pages %}
            <li><a href="{{ page.url }}">{{ page.name }}</a> (Last updated on {{ page.updatedOn|date('F j, Y \\a\\t g:i a') }})
                {% if page.children %}
                    {% import _self as macros %}
                    {{ macros.buildSitemap(page.children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{% import _self as macros %}
{% set sitemap = _api.sitemap.get() %}

{# Pages #}
<h2>Pages</h2>
{{ macros.buildSitemap(sitemap.page) }}

{# Get the blog pages #}
{# This shows assigning the data to a variable before using the page information  #}
<h2>Blog</h2>
{% set home = sitemap.blog.home %}
{% set postList = sitemap.blog.postlist %}
{% set categoryList = sitemap.blog.categorylist|first %}
{% set categories = sitemap.blog.categories %}
<ul>
    <li><a href="{{ home.url }}">Blog home</a></li>
    <li><a href="{{ postList.url }}">Posts</a></li>
    <li><a href="{{ categoryList.url }}">Categories</a>
        {{ macros.buildSitemap(categories) }}
    </li>
</ul>

{# Employment pages #}
{# This shows using the array directly if you only need one value #}
<h2>Employment</h2>

<ul>
    <li><a href="{{ sitemap.employment.home.url }}">Employment home</a></li>
    <li><a href="{{ sitemap.employment.joblist.url }}">Jobs</a>
        {{ macros.buildSitemap(sitemap.employment.jobs) }}
    </li>
</ul>

Get the apps that we need as individual arrays and then pull out the parts we want.

{# This builds the different sections of the sitemap #}
{% macro buildSections(app) %}
    <ul>
        {% for key, section in app  %}
            <li><b>{{ key|ucfirst }}</b>
                {% import _self as macros %}
                {{ macros.buildSitemap(section) }}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{# This builds the unordered list of pages within an app section #}
{% macro buildSitemap(pages) %}
    <ul>
        {% for page in pages %}
            <li><a href="{{ page.url }}">{{ page.name }}</a> (Last updated on {{ page.updatedOn|date('F j, Y \\a\\t g:i a') }})
                {% if page.children %}
                    {% import _self as macros %}
                    {{ macros.buildSitemap(page.children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{% import _self as macros %}

{# Get just the pages #}
{# Because we're not doing anything more with the API results we can simply pass it directly to the macro #}
<h2>Pages</h2>
{{ macros.buildSitemap(_api.sitemap.pages()) }}

{# Get the blog pages #}
{# This shows assigning the API result to a variable before using the page information  #}
<h2>Blog</h2>
{% set blog = _api.sitemap.get('blog') %}
{% set home = blog.home %}
{% set postList = blog.postlist %}
{% set categoryList = blog.categoryList %}
{% set categories = blog.categories %}
<ul>
    <li><a href="{{ home.url }}">Blog home</a></li>
    <li><a href="{{ postList.url }}">Posts</a></li>
    <li><a href="{{ categoryList.url }}">Categories</a>
        {{ macros.buildSitemap(categories) }}
    </li>
</ul>

{# Employment pages #}
{# This shows using the API results directly if you only need one value #}
<h2>Employment</h2>
{% set employment = _api.sitemap.get('employment') %}
<ul>
    <li><a href="{{ employment.home.url }}">Employment home</a></li>
    <li><a href="{{ employment.joblist.url }}">Jobs</a>
        {{ macros.buildSitemap(employment.jobs) }}
    </li>
</ul>

Use the app section filters on the API to retrieve just those specific sections.

{# This builds the different sections of the sitemap #}
{% macro buildSections(app) %}
    <ul>
        {% for key, section in app  %}
            <li><b>{{ key|ucfirst }}</b>
                {% import _self as macros %}
                {{ macros.buildSitemap(section) }}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{# This builds the unordered list of pages within an app section #}
{% macro buildSitemap(pages) %}
    <ul>
        {% for page in pages %}
            <li><a href="{{ page.url }}">{{ page.name }}</a> (Last updated on {{ page.updatedOn|date('F j, Y \\a\\t g:i a') }})
                {% if page.children %}
                    {% import _self as macros %}
                    {{ macros.buildSitemap(page.children) }}
                {% endif %}
            </li>
        {% endfor %}
    </ul>
{% endmacro %}

{% import _self as macros %}

{# Get just the pages #}
{# Because we're not doing anything more with the API results we can simply pass it directly to the macro #}
<h2>Pages</h2>
{{ macros.buildSitemap(_api.sitemap.pages()) }}

{# Get the blog pages #}
{# This shows assigning the API result to a variable before using the page information  #}
<h2>Blog</h2>
{% set home = _api.sitemap.get('blog').home() %}
{% set postList = _api.sitemap.get('blog').postList() %}
{% set categoryList = _api.sitemap.get('blog').categoryList() %}
{% set categories = _api.sitemap.get('blog').categories() %}

<ul>
    <li><a href="{{ home.url }}">Blog home</a></li>
    <li><a href="{{ postList.url }}">Posts</a></li>
    <li><a href="{{ categoryList.url }}">Categories</a>
        {{ macros.buildSitemap(categories) }}
    </li>
</ul>

{# Employment pages #}
{# This shows using the API results directly if you only need one value #}
<h2>Employment</h2>
{% set home = _api.sitemap.get('employment').home() %}
{% set jobList = _api.sitemap.get('employment').jobList() %}
{% set jobs = _api.sitemap.get('employment').jobs() %}
<ul>
    <li><a href="{{ _api.sitemap.get('employment').url }}">Employment home</a></li>
    <li><a href="{{ _api.sitemap.get('employment').url }}">Jobs</a>
        {{ macros.buildSitemap(_api.sitemap.get('employment')) }}
    </li>
</ul>