---
title: "Canonical API"
manual: "TYPO3 Explained"
version: "11.5"
permalink: "https://docs.typo3.org/permalink/t3coreapi:canonicalapi@11.5"
source: "ApiOverview/Seo/CanonicalApi.rst"
rendered: "2026-10-21T15:30:00+00:00"
---

> [!WARNING]
> **Attention**
>
> TYPO3 v11 has reached end-of-life as of October 31th 2024 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).

# Canonical API {#canonicalapi}

A brief explanation happens in [Search engine optimization (SEO)](https://docs.typo3.org/permalink/t3coreapi:seo@11.5).

In general the system will generate the canonical using the same logic as for
cHash.

> [!NOTE]
> The canonical API is provided by the optional system extension
> EXT:seo. You can find information about how to install and use it in the
> [EXT:seo manual](https://docs.typo3.org/c/typo3/cms-seo/11.5/en-us/Index.html).

## Excluding arguments from the generation {#excluding-arguments-from-the-generation}

TYPO3 will fallback to building a URL of current page and appending query strings.
It is possible to exclude specific arguments from being appended.
This is achieved by adding those arguments to a PHP variable:

**EXT:site_package/ext_localconf.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name';
```

It is possible to exclude nested arguments:

**EXT:site_package/ext_localconf.php**

```php
$GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name[second_level]';
```

Arguments in general should be excluded from cHash as well as `additionalCanonicalizedUrlParameters`.
See the possible options in [Caching](https://docs.typo3.org/permalink/t3coreapi:caching@11.5), regarding excluding arguments from cHash.

The idea behind that is:

> If a URL is worth caching (because it has different content) it is worth having a canonical as well.
>
> — [https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/1326#issuecomment-788741312](https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/1326#issuecomment-788741312)

## Using an event to define the URL {#using-an-event-to-define-the-url}

The process will trigger the event [ModifyUrlForCanonicalTagEvent](https://docs.typo3.org/permalink/t3coreapi:modifyurlforcanonicaltagevent@11.5) which can be used to set the actual URL to use.