API: Metadata endpoint use and overview
Note
Anyone interested in using the /metadata endpoint should contact Parse.ly 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/jsonfor the POST request to be properly received.
Path Arguments
| metadata-type | One of posts OR videos. |
Query Parameters
| secret | The 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. |
| metadata | The 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_url | Canonical url for post or page. For page groups, like galleries, it should always point to the main page. |
| urls | Urls 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. ["https://test.com/slideshow/1", "https://test.com/slideshow/2"]) Note: A HTTP/S url schema is required for these urls. |
| page_type | The 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. |
| title | Page or video title. |
| image_url | Url of the image associated with the page or video. |
| pub_date_tmsp | Publication date, formatted as an ISO 8601 UTC timezone string. |
| section | Section 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. |
| authors | Author(s) of the page or video, provided as a list. (e.g. ["Author 1", "Author 2"]) |
| tags | The list of keywords associated with the page or video will map to “Tags” in the Parse.ly dashboard. Note that up to 100 keyword values are supported. |
It may take some time for metadata changes to be reflected in the Parse.ly Dashboard or API results due to caching.
Example
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 https://api.parsely.com/v2/metadata/posts -d '{"apikey": "test.com", "secret": "XXXXX", "metadata":{"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "https://blog.parsely.com/fake-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.
| apikey | test.com |
| secret | XXXXX |
| metadata | {"pub_date_tmsp": "2018-11-30","title": "Fake Title","tags": ["Test"],"authors": ["API Metadata Endpoint"],"canonical_url": "https://blog.parsely.com/fake-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.
| pub_date_tmsp | "2018-11-30" |
| title | "Fake Title" |
| tags | ["Test"] |
| authors | ["API Metadata Endpoint"] |
| canonical_url | "https://blog.parsely.com/fake-url" |
| page_type | "post" |
| section | "Testing" |
| full_content | "Fake content for a fake article." |
| language | "en" |
Technical Caveats
Values in the metadata will appear literally inside Parse.ly 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 Parse.ly 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.
Parse.ly metadata cannot be loaded asynchronously. The Parse.ly 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