Title: Custom metadata setup and options
Author: staff
Published: August 1, 2022
Last modified: November 12, 2025

---

 1. [The Parse.ly API](https://docs.parse.ly/api/)
 2. Custom metadata setup and options

#  Custom metadata setup and options

Though the API attempts to provide all the data and metadata you may need for rendering
site features, there may occasionally be pieces specific to you that would be useful
to have in the API, that are not available in Parse.ly’s data model. For these situations,
we support a `parsely-metadata` meta tag on your article pages, which can add arbitrary
metadata to existing posts.

#### Note

Custom metadata values are available in API responses and within the Data Pipeline(
sold separately); it’s not available in the Parse.ly dashboard.

Add a meta tag to your page with the name “parsely-metadata” and a content field
which is a serialized (and, as needed, quote-escaped) JSON string. For example:

    ```lang-php
    <meta name='parsely-metadata' content='{"type": "feature", "image_url": "http://cdn.site.com/img.jpg"}'>
    ```

## JSON-LD configuration

Alternatively, you can add the metadata as a field to your `json-ld` script tag:

| Parameter | Description | 
| _metadata_ | _(Optional)_ Arbitrary data to attach to post. Must be a valid JSON string. Note that this property is _not_ part of official schemas. |

    ```lang-php
    <script type="application/ld+json">
     {
      "@context": "http://data-pipeline-schema/.org",
      "@type": "NewsArticle",
      "headline": "Zipf's Law of the Internet: Explaining Online Behavior",
      "url": "https://blog.parse.ly/post/57821746552",
      "thumbnailUrl": "https://blog.parse.ly/inline_mra670hTvL1qz4rgp.png",
      "datePublished": "2013-08-15T13:00:00Z",
      "articleSection": "Programming",
      "creator": ["Alan Alexander Milne"],
      "keywords": ["statistics","zipf","internet","behavior"],
      "metadata": [{"type": "feature", "image_url": "http://cdn.site.com/img.jpg"}]
     }
    </script>
    ```

**Escape double quotes in JSON item values**. Double quotes should be escaped with
a backslash symbol like this: `\"`.

Once that is done you can notify the Parse.ly team, who can trigger recrawling of
your site — this will fetch all post pages to sync up the `parsely-metadata` field
with our database. This is to ensure old posts are backfilled with this metadata.

After that you will start receiving the metadata you sent in the `metadata` field
in API. All data in your META tag will simply be passed through, as-is. Note that
these values won’t be displayed in your dashboard.

Technically, the metadata field can store any arbitrary string, but we recommend
you format it as JSON. Also, this string is limited to 2,000 characters — if it 
is longer than that, it is ignored.

Last updated: November 12, 2025