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.
openapi: 3.0.1
info:
title: The New York Times Semantic API
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.\n\n**Note:** In URI examples and field names, *italics* indicate placeholders for\nvariables or values. Parentheses ( ) indicate optional items. Square brackets [ ] are not a convention — when URIs include brackets, interpret them literally.\n\n**The Semantic API at a Glance**\n\n**Base URI**\n\n`http://api.nytimes.com/svc/semantic/v2/concept`\n\n**Scope**\n\nThe New York Times controlled vocabulary (over 100,000 people, places,\norganizations and descriptors used to classify New York Times articles metadata) and New York Times articles from 1981 to today (excludes wire services such as the Associated Press)\n\n**HTTP method**\n\nGET\n\n**Response formats**\n\nJSON\n \n\nGetting Started\n---------------\n\n### KEY CONCEPTS\n\n\nThe first and simplest way to access the API is to refer to a concept is by type. There are seven concept types: people, places, organizations, descriptors, creative work titles, topics, and public companies. The concept\\_type is a mandatory parameter for accessing the Semantic API with a concept type request.\n\nExamples of specific concepts, and their associated concept\\_type: \n\n\n| **Concept Type** | **concept\\_type** | **specific\\_concept\\_name** |\n|------------------|-------------------|----------------------------------|\n| Descriptor | nytd\\_des | Absenteeism |\n| Location | nytd\\_geo | Acapulco (Mexico) |\n| Organization | nytd\\_org | 3M Company |\n| Person | nytd\\_per | Abbas, Mahmoud |\n| Public Company | nytd\\_porg | |\n| Title | nytd\\_ttl | The Joy of Painting (TV Program) |\n| Topic | nytd\\_topic | |\n\n\nIf you wish to determine which articles are associated with a particular\nconcept, you can use the article search API and specify the concept in the fq parameter.\n\n| **Concept Type** | **specific\\_concept\\_name** | **Search API Query** |\n|------------------|----------------------------------|-----------------------------------------------------|\n| Descriptor | Absenteeism | subject:absenteeism |\n| Location | Acapulco (Mexico) | glocations: \"Acapulco (Mexico)\" |\n| Organization | 3M Company | organizations: \"3M Company\" |\n| Person | Abbas, Mahmoud | persons: \"Abbas, Mahmoud\" |\n| Title | The Joy of Painting (TV Program) | creative\\_works: \"The Joy of Painting (TV Program)\" |\n\nIf you are not sure the name and type of the concept that you are looking for, you can use the search endpoint of the semantic API to find concepts by substring.\n\nIn addition to the mandatory parameters corresponding to the three ways of accessing the Semantic API, optional parameters can also be applied. The \"fields\" parameter can be given the value \"all\" to provide a global request that\nincludes all optional parameters.\n\nRequests\n--------\n\nThis section summarizes Semantic Search request URIs and parameters. For best results, first review Key Concepts, then come back here to start building your request URI.\n\n### URI STRUCTURE\n\nSemantic concept requests use the following URI structure:\n\n- **Name**: For concept type and specific concept requests:\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/name/<concept_type>/<specific_concept>.json(?optional_parameters)&api-key=your-API-key\n```\n\n\n- **Search**: For searching the complete list of concepts:\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/search.json(?optional_parameters)&api-key=your-API-key\n\
```\n\n \n\n### \n\nConstructing a Semantic API Request by Concept Type and Specific Concept\n------------------------------------------------------------------------\n\nconcept\\_type is one of seven types:\n\n1. *nytd\\_geo* for a location\n\n2. *nytd\\_per* for a person\n\n3. *nytd\\_org* for an organization\n\n4. *nytd\\_des* for a descriptor\n\n5. *nytd\\_ttl* for a creative work title\n\n6. *nytd\\_topic* for a topic\n\n7. *nytd\\_porg* for a public company\n\nspecific\\_concept\\_name is a term in The New York Times controlled vocabulary.\n\nThe general form for a Semantic API request by concept type and specific concept:\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/name/<concept_type>/<specific_concept_name>.json(?optional_parameters)&api-key=your-API-key\n```\n\nExamples of Semantic API requests by concept type and specific concept:\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/name/nytd_des/Baseball.json?fields=all&api-key=your-API-key\n\nhttp://api.nytimes.com/svc/semantic/v2/concept/name/nytd_per/Obama, Barack.json?fields=pages,links,scope_notes&api-key=your-API-key (you need the space after the comma separating last name and first name)\n```\n \n \nConstructing a Semantic API Search Query\n---------------------------\n\nThe general form for Search Query consists of a query string\n(*query=*query\\_term) and optional parameters.\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/search.json?query=<query_term>(&optional_parameters)&api-key=your-api-key\n```\n\nThe optional parameters for a Search Query are *concept\\_type*,\n*concept\\_uri*, *article\\_uri*. These optional parameters are derived from\nthe other types of Semantic API requests and are explained in the instructions for constructing those requests (above).\n\nAn example of a Search Query, it asks for all of the concepts of type\n'nytd\\_per' that contain the substring \"Evan\" and return the result formatted in\nJSON.\n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/search.json?query=evan&concept_type=nytd_per&api-key=your-api-key\n```\n\n \n-\n\nExamples\n--------\n\nThese examples do not include the required `api-key` parameter. Be sure to\ninclude your API key in your request.\n\n### REQUESTS & RESPONSES\n\n**Request**\n\n- **Name**: Requests all fields for the concept with concept\\_type\n ='nytd\\_geo' and concept\\_name='Kansas'. \n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/name/nytd_geo/Kansas?fields=all&api-key=your-API-key\n```\n\n**Response**\n\n```\n{\n status: \"OK\",\n copyright: \"Copyright (c) 2011 The New York Times Company. All Rights Reserved.\",\n num_results: 1,\n source_database: \"slave\",\n fields: [\"links\", \"taxonomy\", \"combinations\", \"scope_notes\", \"ticker_symbol\", \"geocodes\", \"search_api_query\", \"pages\", \"article_list\"],\n results: [{\n concept_name: \"Kansas\",\n is_times_tag: 1,\n concept_status: \"Active\",\n concept_type: \"nytd_geo\",\n first_use: \"2004-10-30\",\n last_use: \"2011-11-23\",\n use_count: 167,\n links: [{\n relation: \"sameAs\",\n link: \"http://rdf.freebase.com/ns/en.kansas\",\n link_type: \"freebase_uri\",\n link_mapping_type: \"manual\"\n }, {\n relation: \"sameAs\",\n link: \"http://dbpedia.org/resource/Kansas\",\n link_type: \"dbpedia_uri\",\n link_mapping_type: \"manual\"\n }, {\n relation: \"sameAs\",\n link: \"http://en.wikipedia.org/wiki/Kansas\",\n link_type: \"wikipedia_uri\",\n link_mapping_type: \"manual\"\n }],\n taxonomy: [],\n combinations: [],\n scope_notes: [],\n ticker_symbol: [],\n geocodes: [{\n concept_name: \"Kansas\",\n is_times_tag: 1,\n concept_status: \"Active\",\n geoname_id: 4273857,\n name: \"Kansas\",\n latitude: 38.5002888,\n longitude: -98.5006275,\n elevation:
545,\n population: 2740759,\n country_code: \"US\",\n country_name: \"United States\",\n admin_code1: \"KS\",\n admin_code2: null,\n admin_code3: null,\n admin_code4: null,\n admin_name1: \"Kansas\",\n admin_name2: null,\n admin_name3: null,\n admin_name4: null,\n feature_class: \"A\",\n feature_class_name: \"country, state, region,...\",\n feature_code: \"ADM1\",\n feature_code_name: \"first-order administrative division\",\n time_zone_id: \"America/North_Dakota/New_Salem\",\n dst_offset: -5,\n gmt_offset: -6\n }],\n search_api_query: \"http://api.nytimes.com/svc/search/v1/article?format=json&fields=body,date,title,url,byline,small_image_url,small_image_height,small_image_width&query=nytd_geo_facet%3A%5BKansas%5D&api-key=\",\n pages: [\"http://travel.nytimes.com/travel/guides/north-america/united-states/kansas/overview.html\"],\n article_list: {\n offset: \"0\",\n results: [{\n body: \"OVERLAND PARK, Kan. -- The prosecution of a Planned Parenthood affiliate here, the first such criminal case in the nation, has been treated locally as something of a proxy in the battle over abortion rights. Derided by supporters of the organization as politically motivated, the prosecution was celebrated by opponents as the capstone of\",\n byline: \"By A. G. SULZBERGER\",\n date: \"20111123\",\n small_image_height: \"75\",\n small_image_url: \"http://graphics8.nytimes.com/images/2011/11/23/us/23abortion_span/23abortion_span-thumbStandard.jpg\",\n title: \"Abortion Case Loses Ground, But Issue Stays Hot in Kansas\",\n url: \"http://www.nytimes.com/2011/11/23/us/kansas-abortion-prosecution-loses-some-steam-but-fire-is-still-hot.html\"\n }, {\n body: \"CIMARRON, Kan. -- The ubiquitous swerving and darting forms making their hopscotch journey across the landscape here in recent days are part of one of the most storied -- and least celebrated -- natural migrations on the Great Plains. Yes, the tumbleweeds are on the move again. Over the coming weeks, more and more of these vagabond bundles of\",\n byline: \"By A. G. SULZBERGER\",\n date: \"20111028\",\n small_image_height: \"75\",\n small_image_url: \"http://graphics8.nytimes.com/images/2011/10/28/us/TUMBLEWEEDS/TUMBLEWEEDS-thumbStandard.jpg\",\n title: \"Drifting Along, Tumbleweeds Are Piling Up Across Plains\",\n url: \"http://www.nytimes.com/2011/10/28/us/tumbleweeds-are-piling-up-across-the-plains.html\"\n }, {\n body: \"Adding fuel to the debate over his proposal for higher taxes on the rich, Warren E. Buffett said in a letter to a Kansas congressman that he paid $6.9 million in federal income taxes in 2010. The figure represent 17.4 percent of his $39.8 million in taxable income, a percentage he has repeatedly said is too low compared to what his own staff\",\n byline: \"By REUTERS\",\n date: \"20111013\",\n title: \"In Response To Lawmaker, Buffett Claims 17.4% Tax Rate\",\n url: \"http://www.nytimes.com/2011/10/13/business/in-letter-to-congressman-buffett-claims-17-4-tax-rate.html\"\n }, {\n body: \"TOPEKA, Kan. -- The startling vote came up at a City Council meeting here on Tuesday, provoked by a run-of-the-mill budget dispute over services that had spun out of control: decriminalize domestic violence. Three arms of government, all ostensibly representing the same people, have been at an impasse over who should be responsible for -- and pay\",\n byline: \"By A. G. SULZBERGER\",\n date: \"20111012\",\n title: \"Facing Cuts, a City Repeals Its Domestic Violence Law\",\n\
\ url: \"http://www.nytimes.com/2011/10/12/us/topeka-moves-to-decriminalize-domestic-violence.html\"\n }, {\n body: \"A federal judge on Thursday declined to halt a Kansas law that limits the availability of insurance coverage for abortions. The American Civil Liberties Union had requested a temporary injunction against the law, which was approved by the Legislature this year, while the group fights the law in court. Judge Wesley Brown of Federal District Court\",\n byline: \"By TIMOTHY WILLIAMS\",\n date: \"20110930\",\n title: \"NATIONAL BRIEFING | PLAINS; Kansas: Judge Refuses to Block Abortion Law\",\n url: \"http://www.nytimes.com/2011/09/30/us/kansas-judge-refuses-to-block-abortion-law.html\"\n }, {\n body: \"A lawsuit filed in Kansas this month has opened a new front in the legal war over women's reproductive rights. Since last year, 13 states, including Kansas, have enacted laws banning insurance coverage of abortion in the health insurance exchanges created by the federal health care reform law. Some states have gone even further, aggressively\",\n date: \"20110830\",\n title: \"EDITORIAL; Targeting Women: State efforts to end insurance coverage for abortions endanger women's health and rights\",\n url: \"http://www.nytimes.com/2011/08/30/opinion/targeting-women.html\"\n }, {\n body: \"In a foolhardy indulgence of partisan ideology, Gov. Sam Brownback of Kansas is returning a $31.5 million federal grant that would have made his state a leader in technology development for the new federal health care law. The Republican governor's unilateral rejection was presented as a matter of his grave concern over federal deficit problems.\",\n date: \"20110815\",\n title: \"EDITORIAL; Gov. Brownback's Selective Budget Worries\",\n url: \"http://www.nytimes.com/2011/08/15/opinion/gov-brownbacks-selective-budget-worries.html\"\n }, {\n body: \"A federal judge ruled Monday that Planned Parenthood would most likely succeed in overturning a new Kansas law that denies the group access to federal family planning money, saying he believes that the law is unconstitutional and was intended to punish the group for advocating for abortion rights. The judge, J. Thomas Marten, granted Planned\",\n byline: \"By THE ASSOCIATED PRESS\",\n date: \"20110802\",\n title: \"NATIONAL BRIEFING | PLAINS; Kansas: Ruling for Planned Parenthood\",\n url: \"http://www.nytimes.com/2011/08/02/us/02brfs-JUDGERULESFO_BRF.html\"\n }, {\n body: \"SALINA, Kan. -- This state, so sparsely populated in parts that five counties have no doctors at all, has struggled for years to encourage young doctors to relocate to rural communities, where health problems are often exacerbated by a lack of even the most basic care. On Friday, a new medical school campus opened here to provide a novel solution\",\n byline: \"By A. G. SULZBERGER\",\n date: \"20110723\",\n small_image_height: \"75\",\n small_image_url: \"http://graphics8.nytimes.com/images/2011/07/23/us/DOCTORS/DOCTORS-thumbStandard.jpg\",\n title: \"New Path for Small-Town Doctors Starts in a Kansas Small Town\",\n url: \"http://www.nytimes.com/2011/07/23/health/policy/23doctors.html\"\n }, {\n body: \"In three new rulings, federal judges in different states have acted to block immediate enforcement of measures that restrict abortion rights and women's access to affordable contraception, lifesaving cancer screenings and treatment for sexually transmitted diseases. These rulings are important victories for women's health and reproductive rights.\",\n date: \"20110714\",\n title: \"EDITORIAL; The Courts Step In: Judges' recent
rulings show how extreme antiabortion measures have become\",\n url: \"http://www.nytimes.com/2011/07/14/opinion/14thurs1.html\"\n }],\n tokens: [\"nytd_geo_facet:[Kansas]\"],\n total: 167\n },\n concept_uri: \"http://data.nytimes.com/48672515640526970881\"\n }]\n}\n```\n\n**Request**\n\n- **Search: **For all of the concepts of type 'nytd\\_per' that contain the\n substring \"Evan\" and return the result formatted in JSON. \n \n\n```\nhttp://api.nytimes.com/svc/semantic/v2/concept/search.json?query=evan&concept_type=nytd_per&api-key=your-api-key\n```\n\n**Response**\n\n```\n{ \n \"result_set\": { \n \"status\": \"OK\",\n \"copyright\": \"Copyright (c) 2011 The New York Times Company. All Rights Reserved. \", \n \"num_results\": \"1\", \n \"source_database\": \"slave\", \n \"fields\": { \n \"field\": [\"links\",\"search_api_query\"]\n }, \n \"results\": { \n \"result\": {\n \"concept_name\": \"Williams College\",\n \"is_times_tag\": \"0\",\n \"concept_status\": \"Active\",\n \"concept_type\": \"nytd_org\",\n \"first_use\": \"2005-04-03\",\n \"last_use\": \"2010-11-14\",\n \"use_count\": \"12\",\n \"links\": {\n \"link\": [{\"relation\": \"sameAs\",\"link\": \"http://rdf.freebase.com/ns/en.williams_college\",\"link_type\": \"freebase_uri\",\"link_mapping_type\": \"manual\"},\n {\"relation\": \"sameAs\",\"link\": \"http://dbpedia.org/resource/Williams_College\",\"link_type\": \"dbpedia_uri\",\"link_mapping_type\": \"manual\"},\n {\"relation\": \"sameAs\",\"link\": \"http://en.wikipedia.org/wiki/Williams_College\",\"link_type\": \"wikipedia_uri\",\"link_mapping_type\": \"manual\"}]\n }, \n \"search_api_query\": \"http://api.nytimes.com/svc/search/v1/article?format=json&fields=body,date,title,url,byline,small_image_url,small_image_height,small_image_width&query=nytd_org_facet%3A%5BWilliams+College%5D&api-key=\",\"concept_uri\": \"http://data.nytimes.com/N86135070607995494002\"\n }\n }\n }\n }\n```\n"
version: 2.0.0
servers:
- url: http://api.nytimes.com/svc/semantic/v2/concept
- url: https://api.nytimes.com/svc/semantic/v2/concept
security:
- apikey: []
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.
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
/search.json:
get:
parameters:
- 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
- name: offset
in: query
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."
schema:
type: integer
default: 10
- 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.
schema:
type: string
enum:
- all
- pages
- ticker_symbol
- links
- taxonomy
- combinations
- geocodes
- article_list
- scope_notes
- search_api_query
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/ConceptRelation'
tags:
- Search
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
tags:
- name: Name
- name: Search