Signal AI Content Metrics API

openapi: 3.2.0
info:
  title: Signal AI Content Metrics API
  description: '# Overview


    The Signal AI API is an HTTP+JSON API offering programmatic access to Signal AI''s decision augmentation platform.'
  version: v1.3
servers:
- url: https://api.signal-ai.com
security:
- OAuth2:
  - default
tags:
- name: Content Metrics
paths:
  /metrics:
    post:
      operationId: get-metrics
      security:
      - OAuth2:
        - metrics
      tags:
      - Content Metrics
      summary: Metrics API for aggregated analytics
      description: '## Metrics


        The Metrics API provides at-a-glance analytics over all our news & regulatory content. It allows users to monitor, visualise and understand news coverage over time, and enables direct integration with Business Intelligence & data visualisation tools


        The `/metrics` endpoint supports the same expressive query language as our `/search` endpoint, but rather than returning metadata for each individual piece of content, provides aggregated metrics over the results which can be sliced and diced along multiple dimensions: date, publication source, publication country, topics, entities, sentiment, etc.. The limits for these parameters are the same as on the `/search` endpoint (i.e. at most 200 entities, 100 topics...). The exact numbers for each field are detailed in the schema below.


        Example questions the Metrics API can answer in 1 API request / response:


        - How is the coverage (number of articles) and sentiment (negative, neutral and positive coverage) towards my suppliers changing…

        - …over time?

        - …and / or in relation to a set of key ESG topics?

        - …and / or by country of publication?

        - How does overall sentiment towards companies in my portfolio vary by country?

        - What are the top publications (by volume) covering the topics of Cleantech and Sustainable Investments?


        > ⚠️ **Metrics requests are limited to a maximum number of 10,000 aggregation groups**

        >

        > If the number of groups resulting from a query exceeds that limit, the API will return an HTTP 400 response (Bad Request).

        > We would recommend in such instance to break down the metrics query into multiple queries and combine the results. For instance, in order to get daily coverage metrics for 100 entities over 12 months (100 entities X 365 days = 36,500 aggregation groups), you could achieve this with either:

        >

        > - 4 requests for groups of 25 entities (25 entities X 365 days = 9,125 groups per request)

        > - 12 monthly requests for 100 entities (100 entities X 31 days = 3,100 groups per request)


        > ℹ️ **For better performance, use the `where` field to select only relevant documents**

        >

        > Before computing the aggregated metrics, the `where` field is used to reduce the number of

        > documents the system has to process. The more precise the subset of documents is, the faster the

        > results will be computed.


        > ℹ️ **Weekly Aggregation**

        >

        > The date associated with each aggregation bucket in the results will be the date of the first day of that week, so if you query from 2021-01-01 (which was a Friday), the date associated with the first bucket would be 2020-12-28 which was the Monday of the same week.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsQuery'
            examples:
              entity-sentiment-metrics-request:
                $ref: '#/components/examples/entity-sentiment-metrics-request'
              entities-key-topics-metrics-request:
                $ref: '#/components/examples/entities-key-topics-metrics-request'
      responses:
        '200':
          description: Returns aggregate metrics for documents matching the search query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
              examples:
                metrics-response:
                  $ref: '#/components/examples/metrics-response'
components:
  schemas:
    AggregationQueryResourcesIncludeOption:
      type: object
      required:
      - include
      additionalProperties: false
      properties:
        include:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ResourceId'
    ResourceIdsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsResourceId'
      - $ref: '#/components/schemas/AnyResourceIds'
      - $ref: '#/components/schemas/AllResourceIds'
    AggregationMetricKey:
      type: string
      enum:
      - document-count
      - story-count
    DocumentMatch:
      type: object
      additionalProperties: false
      properties:
        story-id:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyResourceIdsMatch'
          - properties:
              any:
                maxItems: 200
        entities:
          $ref: '#/components/schemas/DocumentEntitiesMatch'
        published-at:
          $ref: '#/components/schemas/DateTimeRangeMatch'
        source:
          $ref: '#/components/schemas/SourceMatch'
        keywords:
          $ref: '#/components/schemas/DocumentKeywordsMatch'
        topics:
          $ref: '#/components/schemas/DocumentTopicsMatch'
        categories:
          $ref: '#/components/schemas/CategoriesMatch'
        language:
          $ref: '#/components/schemas/LanguageMatch'
        media-type:
          $ref: '#/components/schemas/MediaTypeMatch'
    SourceExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 500
    ResourceId:
      type: string
      format: uuid
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
      example: bcd2d868-ed38-4382-b94a-622a30fc3215
    AggregationQueryDateIntervalOptions:
      type: object
      required:
      - interval
      additionalProperties: false
      properties:
        interval:
          type: string
          enum:
          - month
          - week
          - day
      default:
        interval: month
    AllTerms:
      type: object
      additionalProperties: false
      required:
      - all
      properties:
        all:
          type: array
          items:
            type: string
    MediaType:
      type: string
      enum:
      - online
      - print
    AnyMediaType:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          type: array
          items:
            $ref: '#/components/schemas/MediaType'
    DateTime:
      type: string
      format: date-time
      description: "A date and time based on the IETF RFC 3339 format (e.g.\n     `2023-01-01T13:37:00` or `2023-01-01T13:37:00Z` for UTC,\n     `2023-01-01T09:37:00-05:00` for EST). Note that UTC is used by default."
      example: '2023-01-01T13:37:00'
    EqualsOrAnyOrAllTermsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsTerm'
      - $ref: '#/components/schemas/AnyTerms'
      - $ref: '#/components/schemas/AllTerms'
    EqualsOrAnyTermsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsTerm'
      - $ref: '#/components/schemas/AnyTerms'
    AggregationsQuery:
      type: object
      required:
      - group-by
      - metrics
      additionalProperties: false
      properties:
        group-by:
          type: array
          uniqueItems: true
          minItems: 1
          maxItems: 6
          items:
            $ref: '#/components/schemas/AggregationDimensionKey'
        options:
          $ref: '#/components/schemas/AggregationQueryOptions'
          description: Options for each group-by dimension
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/AggregationMetricKey'
          default:
          - document-count
          description: Metrics to compute for each group-by dimension
      allOf:
      - if:
          properties:
            group-by:
              contains:
                const: entity
        then:
          required:
          - options
          properties:
            options:
              required:
              - entity
      - if:
          properties:
            group-by:
              contains:
                const: topic
        then:
          required:
          - options
          properties:
            options:
              required:
              - topic
      - if:
          properties:
            group-by:
              contains:
                const: iptc-media-topic
        then:
          required:
          - options
          properties:
            options:
              required:
              - iptc-media-topic
    DocumentTopicsMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                maxItems: 100
              all:
                maxItems: 100
    MetricsQuery:
      type: object
      required:
      - where
      - aggregations
      additionalProperties: false
      properties:
        where:
          $ref: '#/components/schemas/DocumentMatch'
        exclude:
          $ref: '#/components/schemas/ExcludeClause'
        aggregations:
          $ref: '#/components/schemas/AggregationsQuery'
    AggregationQueryOptions:
      type: object
      additionalProperties: false
      properties:
        published-at:
          $ref: '#/components/schemas/AggregationQueryDateIntervalOptions'
          description: The date interval to aggregate on.
        topic:
          $ref: '#/components/schemas/AggregationQueryResourcesIncludeOption'
          description: The topics to aggregate on.
        iptc-media-topic:
          deprecated: true
          $ref: '#/components/schemas/AggregationQueryResourcesIncludeOption'
        entity:
          $ref: '#/components/schemas/AggregationQueryResourcesIncludeOption'
          description: The entities to aggregate on.
        source.country:
          $ref: '#/components/schemas/AggregationQueryTermsIncludeOptions'
          description: The countries to aggregate on.
        language:
          $ref: '#/components/schemas/AggregationQueryTermsIncludeOptions'
          description: The languages to aggregate on.
        source:
          $ref: '#/components/schemas/AggregationQuerySourceOptions'
          description: The sources to aggregate on.
      default:
        published-at:
          interval: month
        source.country:
          size: 10
        language:
          size: 10
        source:
          size: 10
    AllResourceIds:
      type: object
      additionalProperties: false
      required:
      - all
      properties:
        all:
          $ref: '#/components/schemas/ResourceIds'
    DocumentPosition:
      type: string
      enum:
      - title
      - title or summary
      - full content
      - quotes only
    ExcludeClause:
      type: object
      additionalProperties: false
      properties:
        entities:
          $ref: '#/components/schemas/EntitiesExclusion'
        topics:
          $ref: '#/components/schemas/TopicsExclusion'
        source:
          oneOf:
          - $ref: '#/components/schemas/SourceExclusion'
          - $ref: '#/components/schemas/CountryExclusion'
        keywords:
          $ref: '#/components/schemas/KeywordsExclusion'
    TopicsExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 50
    Date:
      type: string
      format: date
      description: "A date based on the IETF RFC 3339 format (e.g. `2023-01-01`).\n    Note that a day is the span of time between 00:00:00 and 23:59:59 based on\n    the UTC timezone. You may prefer using the `date-time` option to match days\n    in a different timezone."
      example: '2023-01-01'
    ResourceIds:
      type: array
      items:
        $ref: '#/components/schemas/ResourceId'
    EqualsOrAnyResourceIdsMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsResourceId'
      - $ref: '#/components/schemas/AnyResourceIds'
    DocumentKeywordsMatch:
      type: object
      required:
      - value
      properties:
        value:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyOrAllTermsMatch'
          - description: There is a 50 word limit for keywords across inclusion and exclusion. See the section **Keyword limitations** above for more details.
        mentions:
          $ref: '#/components/schemas/MentionPositionMatch'
      description: Note that to use inclusion keywords, you will also need to include one of `entities`, `sources` or `topics` in your `where` clause.
    MentionPositionMatch:
      type: object
      additionalProperties: false
      required:
      - position
      properties:
        position:
          $ref: '#/components/schemas/DocumentPosition'
      description: Note that mentions found in `summary` or `quotation` are a subset of the mentions found in the `full content`.
    EqualsResourceId:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          $ref: '#/components/schemas/ResourceId'
    LanguageMatch:
      oneOf:
      - type: object
        additionalProperties: false
        required:
        - eq
        properties:
          eq:
            type: string
            description: Language (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
      - type: object
        name: AnyLanguage
        additionalProperties: false
        required:
        - any
        properties:
          any:
            type: array
            items:
              type: string
            description: A list of languages (e.g. `English`, `Chinese`, `Spanish`, `German`, `Japanese`...)
    DateOrDateTime:
      oneOf:
      - $ref: '#/components/schemas/Date'
      - $ref: '#/components/schemas/DateTime'
    Aggregation:
      type: object
      propertyNames:
        oneOf:
        - $ref: '#/components/schemas/AggregationDimensionKey'
        - $ref: '#/components/schemas/AggregationMetricKey'
    AggregationQueryTermsIncludeOptions:
      type: object
      additionalProperties: false
      properties:
        include:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
        size:
          type: integer
          minimum: 1
          maximum: 100
      default:
        size: 10
    DocumentEntitiesMatch:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                type: array
                maxItems: 200
              all:
                type: array
                maxItems: 200
        salient-only:
          type: boolean
          description: Only return documents for which these entities are salient
        mentions:
          $ref: '#/components/schemas/MentionPositionMatch'
    DateTimeRangeMatch:
      type: object
      properties:
        gt:
          $ref: '#/components/schemas/DateOrDateTime'
        gte:
          $ref: '#/components/schemas/DateOrDateTime'
        lt:
          $ref: '#/components/schemas/DateOrDateTime'
        lte:
          $ref: '#/components/schemas/DateOrDateTime'
      additionalProperties: false
      minProperties: 1
      dependentSchemas:
        gt:
          not:
            required:
            - gte
        gte:
          not:
            required:
            - gt
        lt:
          not:
            required:
            - lte
        lte:
          not:
            required:
            - lt
    AggregationQuerySourceOptions:
      type: object
      additionalProperties: false
      properties:
        size:
          type: integer
          minimum: 1
          maximum: 100
        include:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ResourceId'
      default:
        size: 10
    EntitiesExclusion:
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/AnyResourceIds'
          - properties:
              any:
                maxItems: 100
    AggregationDimensionKey:
      type: string
      enum:
      - published-at
      - source
      - source.country
      - language
      - topic
      - iptc-media-topic
      - entity
      - entity.sentiment
    EqualsMediaType:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          $ref: '#/components/schemas/MediaType'
    MediaTypeMatch:
      oneOf:
      - $ref: '#/components/schemas/EqualsMediaType'
      - $ref: '#/components/schemas/AnyMediaType'
    AnyTerms:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          type: array
          items:
            type: string
    CountryExclusion:
      type: object
      additionalProperties: false
      required:
      - country
      properties:
        country:
          $ref: '#/components/schemas/AnyTerms'
    SourceMatch:
      type: object
      additionalProperties: false
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/EqualsOrAnyResourceIdsMatch'
          - properties:
              any:
                maxItems: 500
        country:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
        region:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
        subregion:
          $ref: '#/components/schemas/EqualsOrAnyTermsMatch'
    KeywordsExclusion:
      type: object
      additionalProperties: false
      required:
      - value
      properties:
        value:
          $ref: '#/components/schemas/AnyTerms'
    MetricsResponse:
      type: object
      required:
      - aggregations
      additionalProperties: false
      properties:
        aggregations:
          type: array
          items:
            $ref: '#/components/schemas/Aggregation'
    EqualsTerm:
      type: object
      additionalProperties: false
      required:
      - eq
      properties:
        eq:
          type: string
    AnyResourceIds:
      type: object
      additionalProperties: false
      required:
      - any
      properties:
        any:
          $ref: '#/components/schemas/ResourceIds'
    CategoriesMatch:
      type: object
      deprecated: true
      additionalProperties: false
      required:
      - id
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/ResourceIdsMatch'
          - properties:
              any:
                maxItems: 100
              all:
                maxItems: 100
  examples:
    entity-sentiment-metrics-request:
      summary: Week-on-week sentiment trend by country
      value:
        where:
          published-at:
            gte: '2021-01-01'
            lt: '2021-04-01'
          entities:
            id:
              eq: c7f15cae-ab0c-4bf5-b345-cea4d3e3ec9b
        aggregations:
          group-by:
          - published-at
          - source.country
          - entity
          - entity.sentiment
          options:
            published-at:
              interval: week
            source.country:
              size: 10
            entity:
              include:
              - c7f15cae-ab0c-4bf5-b345-cea4d3e3ec9b
          metrics:
          - document-count
    metrics-response:
      value:
        aggregations:
        - published-at: '2020-12-28'
          source.country: United States
          entity:
            id: c7f15cae-ab0c-4bf5-b345-cea4d3e3ec9b
            type: organisation
            name: AstraZeneca
          entity.sentiment: negative
          document-count: 126
        - published-at: '2020-12-28'
          source.country: United States
          entity:
            id: c7f15cae-ab0c-4bf5-b345-cea4d3e3ec9b
            type: organisation
            name: AstraZeneca
          entity.sentiment: neutral
          document-count: 5536
        - published-at: '2020-12-28'
          source.country: United States
          entity:
            id: c7f15cae-ab0c-4bf5-b345-cea4d3e3ec9b
            type: organisation
            name: AstraZeneca
          entity.sentiment: positive
          document-count: 6831
    entities-key-topics-metrics-request:
      summary: Competitor sentiment benchmark by key topic
      value:
        where:
          published-at:
            gte: '2020-12-01'
            lt: '2021-02-01'
          topics:
            id:
              any:
              - fc31abf2-7b11-4ed5-a7d2-35266057c0dd
              - c3e9ec2f-e225-4955-9dbf-5480ce3d30fe
              - 4249987d-5b02-4e51-9c44-019dd8e39742
              - a301b00d-f4ef-49fb-9224-f52386d4955e
              - fdcb69a5-8aa6-4067-a29b-f064321e1d7d
          entities:
            id:
              any:
              - a9cf01c5-751f-4fe5-a529-12e0d297cb63
              - c4ad0758-f3ee-4002-84aa-10849a153d75
              - 06608104-0136-4371-ad04-be40fcc306a4
              - d6341968-83df-441c-a869-fa7ae9c22c73
              - d7f0268d-1322-32b2-83d9-bb6fa9922506
        aggregations:
          group-by:
          - published-at
          - topic
          - entity
          - entity.sentiment
          options:
            published-at:
              interval: month
            topic:
              include:
              - fc31abf2-7b11-4ed5-a7d2-35266057c0dd
              - c3e9ec2f-e225-4955-9dbf-5480ce3d30fe
              - 4249987d-5b02-4e51-9c44-019dd8e39742
              - a301b00d-f4ef-49fb-9224-f52386d4955e
              - fdcb69a5-8aa6-4067-a29b-f064321e1d7d
            entity:
              include:
              - a9cf01c5-751f-4fe5-a529-12e0d297cb63
              - c4ad0758-f3ee-4002-84aa-10849a153d75
              - 06608104-0136-4371-ad04-be40fcc306a4
              - d6341968-83df-441c-a869-fa7ae9c22c73
              - d7f0268d-1322-32b2-83d9-bb6fa9922506
          metrics:
          - document-count
  securitySchemes:
    OAuth2:
      type: oauth2
      description: "To obtain the Bearer Token using the Client ID / Secret pair provided to you:\n\n```bash\ncurl -X POST \\\n  -d 'grant_type=client_credentials' \\\n  -d 'client_id=YOUR_CLIENT_ID' \\\n  -d 'client_secret=YOUR_CLIENT_SECRET' \\\n  https://api.signal-ai.com/auth/token\n```\n\nThis will return the following JSON response:\n\n```json\n{\n    \"access_token\": \"eyJhbGciOi…\",\n    \"expires_in\": 86400,\n    …\n}\n```\n\nYou must send the `access_token` from this response in the Authorization header when making requests to other API endpoints:\n\n```bash\ncurl -H \"Authorization: Bearer eyJhbGciOi…\" \\\n  https://api.signal-ai.com/…\n```\n\nAccess tokens will expire 24 hours from the time they were issued.\n"
      flows:
        clientCredentials:
          tokenUrl: https://api.signal-ai.com/auth/token
          scopes:
            default: Access to discovery endpoints
            search: Access to content search endpoint
            metrics: Access to content metrics endpoint
            affinity: Access to concept affinity endpoints
            events: Access to events endpoint
            risk-events: Access to risk events
            manage-organisation: Access to organisation administration endpoints
x-tagGroups:
- name: Concept Discovery
  tags:
  - Publication sources
  - Topics
  - Entities
  - Categories
- name: Search
  tags:
  - Content Search
- name: Metrics
  tags:
  - Content Metrics
- name: Affinity
  x-displayName: Affinity
  tags:
  - Affinity
- name: Events
  x-displayName: Events
  tags:
  - Events
- name: Risk (Alpha)
  tags:
  - Risk Events
- name: Organisation
  tags:
  - Organisation