# Appearance Queries

### Types of Appearance Queries

Appearance Queries can further be divided into two categories:

* Channel Appearances (Require lookup by [company hash](/engagement-api/querying-data/introduction.md#what-is-a-company-hash))
* Content Appearances (Require lookup by content ID)

### Channel Appearances

Channel Appearances identify how the company **and related content** were accessed on a particular channel (such as `Website`, `Print` and `Newsletter`). Channel Appearances are queried using the [company hash](/engagement-api/querying-data/introduction.md#what-is-a-company-hash) and a date range using the format of `{ start: "YYYY-MM", end: "YYYY-MM" }`. It will return the following data for each:

#### Website Channel Appearances

Includes content metadata and website metrics -- notably the following:

* Views: The number of times the company was viewed, including the profile page and related content.
* Users : The total number of users that viewed the company (and related content).
* Rows: A breakout of the above data by each distinct content item.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
query { 
  websiteAppearances(input: {
    companyHash: "COMPANY_HASH_GOES_HERE",
    monthRange: { start: "2022-01", end: "2022-12" }
  }) { 
    views
    users
    rows { 
      views 
      uniqueUsers
      content {
        id
        name
        type 
        published 
        primarySite { 
          id
          name
          title
          shortName
          host
        } 
      } 
    } 
  } 
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "websiteAppearances": {
      "views": 323,
      "users": 235,
      "rows": [
        {
          "views": 64,
          "uniqueUsers": 54,
          "content": {
            "id": 22131807,
            "name": "Content name",
            "type": "Product",
            "published": "2022-03-24T14:59:31.000Z",
            "primarySite": {
              "id": "5f179a9900d6f47b4c98ddec",
              "name": "Website Name",
              "title": "Website Name (WSN)",
              "shortName": "WSN",
              "host": "www.website.com"
            }
          }
        }
        // ...
      ]
    }
  }
}
```

{% endcode %}

</details>

#### Print Channel Appearances

Includes content and print issue metadata.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
  printAppearances(input: {
    companyHash: "585a7978a7bc179300e6b483a107753c",
    monthRange: { start: "2022-01", end: "2022-12" }
  }) {
    content {
      id
      type
      published
    }
    issues {
      id
      name
      mailed
      publication {
        id
        name
      }		
    }
  }
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "printAppearances": [
      {
        "content": {
          "id": 22485616,
          "type": "Article",
          "published": "2022-10-11T16:57:51.000Z"
        },
        "issues": [
          {
            "id": 49945,
            "name": "September/October 2022",
            "mailed": "2022-09-28T05:00:00.000Z",
            "publication": {
              "id": "5f3191b79ad4092e008b4574",
              "name": "Example Publication"
            }
          }
        ]
      }
    ],
  }
}
```

{% endcode %}

</details>

#### Newsletter Channel appearances

Includes content and newsletter deployment metadata.

<details>

<summary>Example query</summary>

{% code title="" %}

```graphql
// Some code
```

{% endcode %}

{% code title="" %}

```json
// Some code
```

{% endcode %}

</details>

## Content Appearances

Content Appearances identify where the individual content item appeared in the channel. Like Channel Appearances, this query identifies where the content item appeared within a channel, and supports a date range using the same format as above.

#### Content Website Appearances

The `contentWebsiteAppearances` query returns website section metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
query {
  contentWebsiteAppearances(input: {
    contentId: 12345678
    monthRange: { start: "2022-01", end: "2022-12" }
  }) {
    content {
      id
      type
      published
    }
    sections {
      id
     name
    }
  }
}
```

{% endcode %}

{% code title="JSON Response" %}

```json
{
  "data": {
    "contentWebsiteAppearances": {
      "content": {
        "id": 12345678,
        "type": "Article",
        "published": "2020-09-02T21:58:24.000Z"
      },
      "sections": [
        {
          "id": 64202,
          "name": "Products"
        }
      ]
    }
  }
}
```

{% endcode %}

</details>

#### Content Print Appearances

The `contentPrintAppearances` query returns magazine issue metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="" %}

```graphql
// Some code
```

{% endcode %}

{% code title="" %}

```json
// Some code
```

{% endcode %}

</details>

#### Content Newsletter Appearances

The `contentNewsletterAppearances` query returns newsletter deployment metadata for each location where the content was scheduled.

<details>

<summary>Example query</summary>

{% code title="GraphQL query" %}

```graphql
newsletterAppearances(input: {
  companyHash: "585a7978a7bc179300e6b483a107753c",
  monthRange: { start: "2022-01", end: "2022-12" }
}) {
  content {
    id
    type
    published
  }
  deployments {
    id
    day
    newsletter {
      id
      name
    }
  }
}
```

{% endcode %}

{% code title="JSON response" %}

```json
{
  "data": {
    "newsletterAppearances": [
      {
        "content": {
          "id": 22485616,
          "type": "Article",
          "published": "2022-10-11T16:57:51.000Z"
        },
        "deployments": [
          {
            "id": "5f20800300d6f47b4c0c58d9.2022-10-12",
            "day": "2022-10-12",
            "newsletter": {
              "id": "5f20800300d6f47b4c0c58d9",
              "name": "Newsletter"
            }
          }
        ]
      },
      {
        "content": {
          "id": 22131807,
          "type": "Product",
          "published": "2022-03-24T14:59:31.000Z"
        },
        "deployments": [
          {
            "id": "5f20800300d6f47b4c0c58d9.2022-03-30",
            "day": "2022-03-30",
            "newsletter": {
              "id": "5f20800300d6f47b4c0c58d9",
              "name": "Newsletter"
            }
          },
          {
            "id": "5f4014f90b2c96a3058b459b.2022-03-24",
            "day": "2022-03-24",
            "newsletter": {
              "id": "5f4014f90b2c96a3058b459b",
              "name": "Product Roundup"
            }
          }
        ]
      }
    ]
  }
}
```

{% endcode %}

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.parameter1.com/engagement-api/querying-data/appearance-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.