The New York Times Company Name API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Semantic Name API
  description: The Semantic API complements the Articles API.
servers:
- url: http://api.nytimes.com/svc/semantic/v2/concept
- url: https://api.nytimes.com/svc/semantic/v2/concept
security:
- apikey: []
tags:
- name: Name
paths:
  /name/{concept-type}/{specific-concept}.json:
    get:
      parameters:
      - name: concept-type
        in: path
        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]".

          '
        required: true
        schema:
          type: string
          enum:
          - nytd_geo
          - nytd_per
          - nytd_org
          - nytd_des
      - name: specific-concept
        in: path
        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".

          '
        required: true
        schema:
          type: string
      - name: fields
        in: query
        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.

          '
        required: false
        schema:
          type: string
          enum:
          - all
          - pages
          - ticker_symbol
          - links
          - taxonomy
          - combinations
          - geocodes
          - article_list
          - scope_notes
          - search_api_query
      - name: query
        in: query
        description: Precedes the search term string. Used in a Search Query. Except for <specific_concept_name>, Search Query will take the required parameters listed above (<concept_type>, <concept_uri>, <article_uri>) as an optional_parameter in addition to the query=<query_term>.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An array of Concepts
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  copyright:
                    type: string
                  num_results:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Concept'
      tags:
      - Name
      summary: Get name by concept type {specific concept} json
      x-summary-source: derived
      operationId: getNameByConceptType{specificConcept}Json
      x-operation-id-source: derived
components:
  schemas:
    Concept:
      type: object
      properties:
        concept_id:
          type: integer
        concept_name:
          type: string
        is_times_tag:
          type: integer
        concept_status:
          type: string
        vernacular:
          type: string
        concept_type:
          type: string
        concept_created:
          type: string
        concept_updated:
          type: string
        taxonomy:
          type: array
          items:
            type: object
            properties:
              source_concept_id:
                type: integer
              target_concept_id:
                type: integer
              source_concept_name:
                type: string
              target_concept_name:
                type: string
              source_concept_type:
                type: string
              target_concept_type:
                type: string
              source_concept_vernacular:
                type: string
              target_concept_vernacular:
                type: string
              taxonomic_relation:
                type: string
              taxonomic_verification_status:
                type: string
        links:
          type: array
          items:
            type: object
            properties:
              concept_id:
                type: integer
              concept_name:
                type: string
              concept_status:
                type: string
              is_times_tag:
                type: integer
              concept_type:
                type: string
              link_id:
                type: integer
              relation:
                type: string
              link:
                type: string
              link_type:
                type: string
              mapping_type:
                type: string
        search_api_query:
          type: string
        article_list:
          type: object
          properties:
            results:
              type: array
              items:
                type: object
                properties:
                  body:
                    type: string
                  byline:
                    type: string
                  concepts:
                    type: object
                    properties:
                      nytd_des:
                        type: array
                        items:
                          type: string
                      nytd_org:
                        type: array
                        items:
                          type: string
                      nytd_per:
                        type: array
                        items:
                          type: string
                  date:
                    type: string
                  document_type:
                    type: string
                  title:
                    type: string
                  type_of_material:
                    type: string
                  url:
                    type: string
            total:
              type: integer
        scope_notes:
          type: array
          items:
            type: object
            properties:
              scope_note:
                type: string
              scope_note_name:
                type: string
              scope_note_type:
                type: string
        combinations:
          type: array
          items:
            type: object
            properties:
              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
              combination_note:
                type: string
        ancestors:
          type: array
          items:
            $ref: '#/components/schemas/ConceptRelation'
        descendants:
          type: array
          items:
            $ref: '#/components/schemas/ConceptRelation'
    ConceptRelation:
      type: object
      properties:
        concept_id:
          type: integer
        concept_name:
          type: string
        is_times_tag:
          type: integer
        concept_status:
          type: string
        vernacular:
          type: string
        concept_type:
          type: string
        concept_created:
          type: string
        concept_updated:
          type: string
  securitySchemes:
    apikey:
      type: apiKey
      name: api-key
      in: query