openapi: 3.0.0
servers:
  - url: http://api.nytimes.com/svc/semantic/v2/concept
  - url: https://api.nytimes.com/svc/semantic/v2/concept
info:
  description: |
    The Semantic API complements the Articles API. With the Semantic API, you get access to the long list of people, places, organizations and other locations, entities and descriptors that make up the controlled vocabulary used as metadata by The New York Times (sometimes referred to as Times Tags and used for Times Topics pages).

    The Semantic API uses concepts which are, by definition, terms in The New York Times controlled vocabulary. Like the way facets are used in the Articles API, concepts are a good way to uncover articles of interest in The New York Times archive, and at the same time, limit the scope and number of those articles. The Semantic API maps to external semantic data resources, in a fashion consistent with the idea of linked data. The Semantic API also provides combination and relationship information to other, similar concepts in The New York Times controlled vocabulary.
  termsOfService: http://developer.nytimes.com/tou
  title: Semantic API
  version: 2.0.0
  x-apiClientRegistration:
    url: http://developer.nytimes.com/signup
  x-apisguru-categories:
    - media
    - open_data
  x-logo:
    url: https://static01.nyt.com/images/icons/t_logo_291_black.png
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/semantic_api/semantic_api.json
      version: "3.0"
  x-providerName: nytimes.com
  x-serviceName: semantic_api
externalDocs:
  url: http://developer.nytimes.com/
security:
  - apikey: []
paths:
  /name/{concept-type}/{specific-concept}.json:
    get:
      parameters:
        - description: |
            The type of the concept, used for Constructing a Semantic API Request by Concept Type and Specific Concept Name. The parameter is defined as a name-value pair, as in "concept_type=[nytd_geo|nytd_per|nytd_org|nytd_des]".
          in: path
          name: concept-type
          required: true
          schema:
            enum:
              - nytd_geo
              - nytd_per
              - nytd_org
              - nytd_des
            type: string
        - description: |
            The name of the concept, used for Constructing a Semantic API Request by Concept Type and Specific Concept Name. The parameter is defined in the URI path, as the element immediately preceding ".json" like with "Baseball.json".
          in: path
          name: specific-concept
          required: true
          schema:
            type: string
        - description: |
            "all" or comma-separated list of specific optional fields: pages, ticker_symbol, links, taxonomy, combinations, geocodes, article_list, scope_notes, search_api_query

            Optional fields are returned in result_set. They are briefly explained here:

            pages: A list of topic pages associated with a specific concept.
            ticker_symbol: If this concept is a publicly traded company, this field contains the ticker symbol.
            links: A list of links from this concept to external data resources.
            taxonomy: For descriptor concepts, this field returns a list of taxonomic relations to other concepts.
            combinations: For descriptor concepts, this field returns a list of the specific meanings tis concept takes on when combined with other concepts.
            geocodes: For geographic concepts, the full GIS record from geonames.
            article_list: A list of up to 10 articles associated with this concept.
            scope_notes: Scope notes contains clarifications and meaning definitions that explicate the relationship between the concept and an article.
            search_api_query: Returns the request one would need to submit to the Article Search API to obtain a list of articles annotated with this concept.
          in: query
          name: fields
          required: false
          schema:
            enum:
              - all
              - pages
              - ticker_symbol
              - links
              - taxonomy
              - combinations
              - geocodes
              - article_list
              - scope_notes
              - search_api_query
            type: string
        - description: Precedes the search term string. Used in a Search Query. Except for &lt;specific_concept_name&gt;, Search Query will take the required parameters listed above (&lt;concept_type&gt;, &lt;concept_uri&gt;, &lt;article_uri&gt;) as an optional_parameter in addition to the query=&lt;query_term&gt;.
          in: query
          name: query
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/Concept"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Concepts
  /search.json:
    get:
      parameters:
        - description: Precedes the search term string. Used in a Search Query. Except for &lt;specific_concept_name&gt;, Search Query will take the required parameters listed above (&lt;concept_type&gt;, &lt;concept_uri&gt;, &lt;article_uri&gt;) as an optional_parameter in addition to the query=&lt;query_term&gt;.
          in: query
          name: query
          required: true
          schema:
            type: string
        - description: Integer value for the index count from the first concept to the last concept, sorted alphabetically. Used in a Search Query. A Search Query will return up to 10 concepts in its results.
          in: query
          name: offset
          required: false
          schema:
            default: 10
            type: integer
        - description: |
            "all" or comma-separated list of specific optional fields: pages, ticker_symbol, links, taxonomy, combinations, geocodes, article_list, scope_notes, search_api_query

            Optional fields are returned in result_set. They are briefly explained here:

            pages: A list of topic pages associated with a specific concept.
            ticker_symbol: If this concept is a publicly traded company, this field contains the ticker symbol.
            links: A list of links from this concept to external data resources.
            taxonomy: For descriptor concepts, this field returns a list of taxonomic relations to other concepts.
            combinations: For descriptor concepts, this field returns a list of the specific meanings tis concept takes on when combined with other concepts.
            geocodes: For geographic concepts, the full GIS record from geonames.
            article_list: A list of up to 10 articles associated with this concept.
            scope_notes: Scope notes contains clarifications and meaning definitions that explicate the relationship between the concept and an article.
            search_api_query: Returns the request one would need to submit to the Article Search API to obtain a list of articles annotated with this concept.
          in: query
          name: fields
          required: false
          schema:
            enum:
              - all
              - pages
              - ticker_symbol
              - links
              - taxonomy
              - combinations
              - geocodes
              - article_list
              - scope_notes
              - search_api_query
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    items:
                      $ref: "#/components/schemas/ConceptRelation"
                    type: array
                  status:
                    type: string
                type: object
          description: An array of Concepts
components:
  schemas:
    Concept:
      properties:
        ancestors:
          items:
            $ref: "#/components/schemas/ConceptRelation"
          type: array
        article_list:
          properties:
            results:
              items:
                properties:
                  body:
                    type: string
                  byline:
                    type: string
                  concepts:
                    properties:
                      nytd_des:
                        items:
                          type: string
                        type: array
                      nytd_org:
                        items:
                          type: string
                        type: array
                      nytd_per:
                        items:
                          type: string
                        type: array
                    type: object
                  date:
                    type: string
                  document_type:
                    type: string
                  title:
                    type: string
                  type_of_material:
                    type: string
                  url:
                    type: string
                type: object
              type: array
            total:
              type: integer
          type: object
        combinations:
          items:
            properties:
              combination_note:
                type: string
              combination_source_concept_id:
                type: integer
              combination_source_concept_name:
                type: string
              combination_source_concept_type:
                type: string
              combination_target_concept_id:
                type: integer
              combination_target_concept_name:
                type: string
              combination_target_concept_type:
                type: string
            type: object
          type: array
        concept_created:
          type: string
        concept_id:
          type: integer
        concept_name:
          type: string
        concept_status:
          type: string
        concept_type:
          type: string
        concept_updated:
          type: string
        descendants:
          items:
            $ref: "#/components/schemas/ConceptRelation"
          type: array
        is_times_tag:
          type: integer
        links:
          items:
            properties:
              concept_id:
                type: integer
              concept_name:
                type: string
              concept_status:
                type: string
              concept_type:
                type: string
              is_times_tag:
                type: integer
              link:
                type: string
              link_id:
                type: integer
              link_type:
                type: string
              mapping_type:
                type: string
              relation:
                type: string
            type: object
          type: array
        scope_notes:
          items:
            properties:
              scope_note:
                type: string
              scope_note_name:
                type: string
              scope_note_type:
                type: string
            type: object
          type: array
        search_api_query:
          type: string
        taxonomy:
          items:
            properties:
              source_concept_id:
                type: integer
              source_concept_name:
                type: string
              source_concept_type:
                type: string
              source_concept_vernacular:
                type: string
              target_concept_id:
                type: integer
              target_concept_name:
                type: string
              target_concept_type:
                type: string
              target_concept_vernacular:
                type: string
              taxonomic_relation:
                type: string
              taxonomic_verification_status:
                type: string
            type: object
          type: array
        vernacular:
          type: string
      type: object
    ConceptRelation:
      properties:
        concept_created:
          type: string
        concept_id:
          type: integer
        concept_name:
          type: string
        concept_status:
          type: string
        concept_type:
          type: string
        concept_updated:
          type: string
        is_times_tag:
          type: integer
        vernacular:
          type: string
      type: object
  securitySchemes:
    apikey:
      in: query
      name: api-key
      type: apiKey
