Skip to content

API: Metadata endpoint use and overview


Anyone interested in using the /metadata endpoint should contact Support before doing so.

POST /metadata/(metadata-type)

Updates the metadata for a post or video (depending on the specified metadata-type) using the received metadata dictionary.

This endpoint uses a different secret value from our other endpoints for security purposes. Please reach out to your account manager for details on how to identify the write-only secret value that should be used for this endpoint.

Details on providing on-page metadata can be found here.

The Content-Type header must be set to application/json for the POST request to be properly received.

Path Arguments

metadata-typeOne of posts OR videos.

Query Parameters

secretThe write-only secret value. This differs from the standard secret value use for other endpoints. Please reach out to your account manager for details on how to identify the write-only secret value that should be used for this endpoint.
metadataThe JSON object of metadata you would like to be written to our systems. The requisite format of this value is detailed below.

The Metadata Parameter

The metadata parameter should be a JSON object with the following schema:

canonical_urlCanonical url for post or page. For page groups, like galleries, it should always point to the main page.
urlsUrls that should be aliased to the canonical_url (the traffic for these urls and the canonical_url will be combined to form a single record) provided as a list. (e.g. ["", ""]) Note: A HTTP/S url schema is required for these urls.
page_typeThe type of page between: post, index, video. See “Distinguishing between posts and pages” for more information on what differentiates and post and an index page.
titlePage or video title.
image_urlUrl of the image associated with the page or video.
pub_date_tmspPublication date, formatted as an ISO 8601 UTC timezone string.
sectionSection the page is a part of. (e.g. "Politics"). Note that only 1 section value is supported. Therefore, it is recommended that the top-level section or category is used and any sub-sections or child categories are added to tags.
authorsAuthor(s) of the page or video, provided as a list. (e.g. ["Author 1", "Author 2"])
tagsThe list of keywords associated with the page or video will map to “Tags” in the dashboard. Note that up to 100 keyword values are supported.

It may take some time for metadata changes to be reflected in the Dashboard or API results due to caching.


We used the following methodology to send metadata for a PDF as discussed in our “Track Files” doc.

An example of a curl call you can execute in a command line is below.

curl -H "Content-Type: application/json" -X POST -d '{"apikey": "", "secret": "XXXXX", "metadata":{"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "","page_type": "post","section": "Testing", "full_content": "Fake content for a fake article.", "language": "en"}}'

This request has the following url-encoded fields and values.
metadata{"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "","page_type": "post","section": "Testing", "full_content": "Fake content for a fake article.", "language": "en"}

The metadata JSON object has the following fields and values.

title"Fake Title"
authors["API Metadata Endpoint"]
full_content"Fake content for a fake article."

Technical Caveats

Values in the metadata will appear literally inside Analytics. Remember that all metadata is case sensitive. String values supplied here (specifically title, authors, and section) as well as list values (specifically tags) will appear in analytics exactly as they are specified in the tag. As a result, make sure to use proper capitalization and specify the values as you expect them to appear. Values with variations (example: “John Smith” and “john smith”) will appear separately in the Dashboard causing duplication and skewed data. metadata cannot be loaded asynchronously. The crawler will not execute JavaScript. It must be able to access the meta tags from the results of a single GET request.

Last updated: August 16, 2023