---
title: "Canonical API"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:canonicalapi@main"
source: "ApiOverview/Seo/CanonicalApi.rst"
modified: "2026-09-15T19:16:38+00:00"
---

# Canonical API

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

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/main/en-us/Index.html).

## Including specific arguments for the URL generation

TYPO3 will building a URI of the current page and append query strings
which are needed for the cHash calculation (vital arguments to uniquely identify
the given content URI). This is especially important with for example detail pages of records. The query parameters are crucial to show the right content.

It is possible to additionally include specific arguments.
This is achieved by adding those arguments to the configuration:

**EXT:site_package/ext_localconf.php**

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

It is possible to include nested arguments:

**EXT:site_package/ext_localconf.php**

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

Non-vital arguments in general should be excluded from cHash and not be listed as `additionalCanonicalizedUrlParameters`.
See the possible options in [Caching](https://docs.typo3.org/permalink/t3coreapi:caching@main) 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

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