TIMDEX API Reference

Welcome to the TIMDEX API!

Contact

API Support

License

Apache 2.0

https://www.apache.org/licenses/LICENSE-2.0.html

API Endpoints

# Production:
https://timdex.mit.edu/graphql

TIMDEX Overview, Guides, and Tutorials

These reference docs are only part of our documentation. Please also see our Guides and Tutorials.

Queries

`info`

Description

Information about the current endpoint

Response

Returns an Info!

Example

Query

query Info {
  info {
    name
    tagline
    version {
      distribution
      luceneVersion
      number
    }
  }
}

Response

{
  "data": {
    "info": {
      "name": "abc123",
      "tagline": "xyz789",
      "version": Version
    }
  }
}

Queries

`ping`

Description

Is this thing on?

Response

Returns a String!

Example

Query

query Ping {
  ping
}

Response

{"data": {"ping": "xyz789"}}

Queries

`recordId`

Description

Retrieve one timdex record

Response

Returns a Record!

Arguments

Name	Description
`id` - `String!`
`index` - `String`	It is not recommended to provide an index value unless we have provided you with one for your specific use case. Default = `null`

Example

Query

query RecordId(
  $id: String!,
  $index: String
) {
  recordId(
    id: $id,
    index: $index
  ) {
    alternateTitles {
      kind
      value
    }
    callNumbers
    citation
    contentType
    contents
    contributors {
      affiliation
      identifier
      kind
      mitAffiliated
      value
    }
    dates {
      kind
      note
      range {
        ...DateRangeFragment
      }
      value
    }
    dois
    edition
    fileFormats
    format
    fundingInformation {
      awardNumber
      awardUri
      funderIdentifier
      funderIdentifierType
      funderName
    }
    highlight {
      matchedField
      matchedPhrases
    }
    holdings {
      callnumber
      collection
      format
      location
      notes
      summary
    }
    identifier
    identifiers {
      kind
      value
    }
    imprint
    inBibliography
    isbns
    issns
    languages
    lccn
    links {
      kind
      restrictions
      text
      url
    }
    literaryForm
    locations {
      geopoint
      kind
      value
    }
    notes {
      kind
      value
    }
    numbering
    oclcs
    physicalDescription
    placeOfPublication
    publicationDate
    publicationFrequency
    publicationInformation
    relatedItems {
      description
      itemType
      kind
      relationship
      uri
      value
    }
    relatedPlace
    rights {
      description
      kind
      uri
    }
    score
    source
    sourceLink
    subjects {
      kind
      value
    }
    summary
    timdexRecordId
    title
  }
}

Variables

{"id": "xyz789", "index": null}

Response

{
  "data": {
    "recordId": {
      "alternateTitles": [AlternateTitle],
      "callNumbers": ["abc123"],
      "citation": "abc123",
      "contentType": ["abc123"],
      "contents": ["abc123"],
      "contributors": [Contributor],
      "dates": [Date],
      "dois": ["xyz789"],
      "edition": "abc123",
      "fileFormats": ["abc123"],
      "format": ["abc123"],
      "fundingInformation": [Funding],
      "highlight": [Highlight],
      "holdings": [Holding],
      "identifier": "4",
      "identifiers": [Identifer],
      "imprint": ["abc123"],
      "inBibliography": ["abc123"],
      "isbns": ["abc123"],
      "issns": ["xyz789"],
      "languages": ["abc123"],
      "lccn": "xyz789",
      "links": [Link],
      "literaryForm": "abc123",
      "locations": [Location],
      "notes": [Note],
      "numbering": "abc123",
      "oclcs": ["xyz789"],
      "physicalDescription": "xyz789",
      "placeOfPublication": "abc123",
      "publicationDate": "abc123",
      "publicationFrequency": ["abc123"],
      "publicationInformation": ["abc123"],
      "relatedItems": [RelatedItem],
      "relatedPlace": ["abc123"],
      "rights": [Rights],
      "score": "abc123",
      "source": "abc123",
      "sourceLink": "abc123",
      "subjects": [Subject],
      "summary": ["abc123"],
      "timdexRecordId": 4,
      "title": "xyz789"
    }
  }
}

Queries

`search`

Description

Search for timdex records

Response

Returns a Search!

Arguments

Name	Description
`searchterm` - `String`	Query all searchable fields. Default = `null`
`citation` - `String`	Search by citation information. Default = `null`
`contributors` - `String`	Search by contributor name; e.g., author, editor, etc. Default = `null`
`fundingInformation` - `String`	Search by funding information; e.g., funding source, award name, etc. Default = `null`
`identifiers` - `String`	Search by unique indentifier; e.g., ISBN, DOI, etc. Default = `null`
`locations` - `String`	Search by locations. Default = `null`
`subjects` - `String`	Search by subject terms. Default = `null`
`title` - `String`	Search by title. Default = `null`
`from` - `String`	Search result number to begin with (the first result is 0). Default = `"0"`
`index` - `String`	It is not recommended to provide an index value unless we have provided you with one for your specific use case. Default = `null`
`contentTypeFilter` - `[String!]`	Filter results by content type. Use the `contentType` aggregation for a list of possible values. Default = `null`
`contributorsFilter` - `[String!]`	Filter results by contributor. Use the `contributors` aggregation for a list of possible values. Default = `null`
`formatFilter` - `[String!]`	Filter results by format. Use the `format` aggregation for a list of possible values. Default = `null`
`languagesFilter` - `[String!]`	Filter results by language. Use the `languages` aggregation for a list of possible values. Default = `null`
`literaryFormFilter` - `String`	Filter results by fiction or nonfiction. Default = `null`
`sourceFilter` - `[String!]`	Filter by source record system. Use the `sources` aggregation for a list of possible values. Default = `null`
`subjectsFilter` - `[String!]`	Filter by subject terms. Use the `contentType` aggregation for a list of possible values. Default = `null`

Example

Query

query Search(
  $searchterm: String,
  $citation: String,
  $contributors: String,
  $fundingInformation: String,
  $identifiers: String,
  $locations: String,
  $subjects: String,
  $title: String,
  $from: String,
  $index: String,
  $contentTypeFilter: [String!],
  $contributorsFilter: [String!],
  $formatFilter: [String!],
  $languagesFilter: [String!],
  $literaryFormFilter: String,
  $sourceFilter: [String!],
  $subjectsFilter: [String!]
) {
  search(
    searchterm: $searchterm,
    citation: $citation,
    contributors: $contributors,
    fundingInformation: $fundingInformation,
    identifiers: $identifiers,
    locations: $locations,
    subjects: $subjects,
    title: $title,
    from: $from,
    index: $index,
    contentTypeFilter: $contentTypeFilter,
    contributorsFilter: $contributorsFilter,
    formatFilter: $formatFilter,
    languagesFilter: $languagesFilter,
    literaryFormFilter: $literaryFormFilter,
    sourceFilter: $sourceFilter,
    subjectsFilter: $subjectsFilter
  ) {
    aggregations {
      contentType {
        ...AggregationCountFragment
      }
      contributors {
        ...AggregationCountFragment
      }
      format {
        ...AggregationCountFragment
      }
      languages {
        ...AggregationCountFragment
      }
      literaryForm {
        ...AggregationCountFragment
      }
      source {
        ...AggregationCountFragment
      }
      subjects {
        ...AggregationCountFragment
      }
    }
    hits
    records {
      alternateTitles {
        ...AlternateTitleFragment
      }
      callNumbers
      citation
      contentType
      contents
      contributors {
        ...ContributorFragment
      }
      dates {
        ...DateFragment
      }
      dois
      edition
      fileFormats
      format
      fundingInformation {
        ...FundingFragment
      }
      highlight {
        ...HighlightFragment
      }
      holdings {
        ...HoldingFragment
      }
      identifier
      identifiers {
        ...IdentiferFragment
      }
      imprint
      inBibliography
      isbns
      issns
      languages
      lccn
      links {
        ...LinkFragment
      }
      literaryForm
      locations {
        ...LocationFragment
      }
      notes {
        ...NoteFragment
      }
      numbering
      oclcs
      physicalDescription
      placeOfPublication
      publicationDate
      publicationFrequency
      publicationInformation
      relatedItems {
        ...RelatedItemFragment
      }
      relatedPlace
      rights {
        ...RightsFragment
      }
      score
      source
      sourceLink
      subjects {
        ...SubjectFragment
      }
      summary
      timdexRecordId
      title
    }
  }
}

Variables

{
  "searchterm": null,
  "citation": null,
  "contributors": null,
  "fundingInformation": null,
  "identifiers": null,
  "locations": null,
  "subjects": null,
  "title": null,
  "from": "0",
  "index": null,
  "contentTypeFilter": null,
  "contributorsFilter": null,
  "formatFilter": null,
  "languagesFilter": null,
  "literaryFormFilter": null,
  "sourceFilter": null,
  "subjectsFilter": null
}

Response

{
  "data": {
    "search": {
      "aggregations": Aggregations,
      "hits": 123,
      "records": [Record]
    }
  }
}

Types

AggregationCount

Fields

Field Name	Description
`docCount` - `Int`	Result count for a given aggregation
`key` - `String`	Aggregation value matched in search

Example

{"docCount": 987, "key": "abc123"}

Types

Aggregations

Fields

Field Name	Description
`contentType` - `[AggregationCount!]`	Total search results by content type
`contributors` - `[AggregationCount!]`	Total search results by contributor name; e.g., author, editor, etc.
`format` - `[AggregationCount!]`	Total search results by format
`languages` - `[AggregationCount!]`	Total search results by language
`literaryForm` - `[AggregationCount!]`	Total search results by fiction or nonfiction
`source` - `[AggregationCount!]`	Total search results by source record system
`subjects` - `[AggregationCount!]`	Total search results by subject term

Example

{
  "contentType": [AggregationCount],
  "contributors": [AggregationCount],
  "format": [AggregationCount],
  "languages": [AggregationCount],
  "literaryForm": [AggregationCount],
  "source": [AggregationCount],
  "subjects": [AggregationCount]
}

Types

AlternateTitle

Fields

Field Name	Description
`kind` - `String`	Type of alternate title
`value` - `String`	Value of alternate title

Example

{
  "kind": "xyz789",
  "value": "xyz789"
}

Types

Boolean

Description

Represents true or false values.

Types

Contributor

Fields

Field Name	Description
`affiliation` - `[String!]`	Institutional affiliation(s) of a contributor
`identifier` - `[String!]`	Unique identifier(s) of a contributor
`kind` - `String`	Type of contributor; e.g., editor, author, etc.
`mitAffiliated` - `Boolean`	Identifies whether a contributor is affiliated with MIT
`value` - `String!`	Name of contributor

Example

{
  "affiliation": ["xyz789"],
  "identifier": ["xyz789"],
  "kind": "abc123",
  "mitAffiliated": false,
  "value": "xyz789"
}

Types

Date

Fields

Field Name	Description
`kind` - `String!`	Type of date; e.g., "creation", "accessioned", etc.
`note` - `String`	Notes about the date, if applicable
`range` - `DateRange`	Range of dates
`value` - `String`	Value of date. Note that date ranges will be returned in the `range` subfield

Example

{
  "kind": "xyz789",
  "note": "xyz789",
  "range": DateRange,
  "value": "xyz789"
}

Types

DateRange

Fields

Field Name	Description
`gte` - `String`	Beginning of date range
`lte` - `String`	End of date range

Example

{
  "gte": "abc123",
  "lte": "abc123"
}

Types

Funding

Fields

Field Name	Description
`awardNumber` - `String`	Grant award number
`awardUri` - `String`	Grant award URI
`funderIdentifier` - `String`	Unique identifier for funding source
`funderIdentifierType` - `String`	Type of unique indentifier for funding source
`funderName` - `String`	Name of funding source

Example

{
  "awardNumber": "abc123",
  "awardUri": "abc123",
  "funderIdentifier": "abc123",
  "funderIdentifierType": "xyz789",
  "funderName": "abc123"
}

Types

Highlight

Fields

Field Name	Description
`matchedField` - `String`	The field that was matched by search terms
`matchedPhrases` - `[String!]`	The phrases within a field that were matched

Example

{
  "matchedField": "xyz789",
  "matchedPhrases": ["xyz789"]
}

Types

Holding

Fields

Field Name	Description
`callnumber` - `String`	Call number of the holding
`collection` - `String`	Collection in which the item is held
`format` - `String`	Format of the holding
`location` - `String`	Physical location of the holding
`notes` - `String`	Cataloging notes about the holding
`summary` - `String`	Summary holdings information

Example

{
  "callnumber": "abc123",
  "collection": "xyz789",
  "format": "abc123",
  "location": "abc123",
  "notes": "xyz789",
  "summary": "xyz789"
}

Types

ID

Description

Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.

Example

Types

Identifer

Fields

Field Name	Description
`kind` - `String!`	Type of identifier
`value` - `String!`	Value of identifier

Example

{
  "kind": "abc123",
  "value": "xyz789"
}

Types

Info

Fields

Field Name	Description
`name` - `String!`
`tagline` - `String!`
`version` - `Version!`

Example

{
  "name": "abc123",
  "tagline": "xyz789",
  "version": Version
}

Types

Int

Description

Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

Link

Fields

Field Name	Description
`kind` - `String`	Type of link
`restrictions` - `String`	Restrictions on a link, if available
`text` - `String`	Additional description of a link, if applicable
`url` - `String!`	URL of a link

Example

{
  "kind": "xyz789",
  "restrictions": "abc123",
  "text": "xyz789",
  "url": "xyz789"
}

Types

Location

Fields

Field Name	Description
`geopoint` - `String`	GeoPoint data for the location, if applicable
`kind` - `String`	Type of location
`value` - `String`	Name of location

Example

{
  "geopoint": "abc123",
  "kind": "abc123",
  "value": "abc123"
}

Types

Note

Fields

Field Name	Description
`kind` - `String`	Type of note
`value` - `[String!]`	Value of note

Example

{
  "kind": "abc123",
  "value": ["abc123"]
}

Types

Record

Fields

Field Name	Description
`alternateTitles` - `[AlternateTitle!]`	Alternate titles for the item
`callNumbers` - `[String!]`	Identification number used to classify and locate item
`citation` - `String`	Citation for item
`contentType` - `[String!]`	Type of content of item; e.g., "still image", "text", etc.
`contents` - `[String!]`	Table of contents for item
`contributors` - `[Contributor!]`	Contributors to the item; e.g., authors, editors, etc.
`dates` - `[Date!]`	Dates associated with item, including publication date
`dois` - `[String!]`	Use `identifiers`
`edition` - `String`	Edition information for item
`fileFormats` - `[String!]`	Available file formats for the item
`format` - `[String!]`	Format of item e.g. "Print Volume", "DVD", etc.
`fundingInformation` - `[Funding!]`	Funding information for the item
`highlight` - `[Highlight!]`	Search term matches in item metadata
`holdings` - `[Holding!]`	Local holdings of the item
`identifier` - `ID!`	Use `timdex_record_id`
`identifiers` - `[Identifer!]`	Unique identifiers associated with the item; e.g., ISBN, DOI, etc.
`imprint` - `[String!]`	Use `publicationInformation`
`inBibliography` - `[String!]`	Use `related_items`
`isbns` - `[String!]`	Use `identifiers`
`issns` - `[String!]`	Use `identifiers`
`languages` - `[String!]`	Language(s) of item
`lccn` - `String`	Use `identifiers`
`links` - `[Link!]`	Link(s) to item
`literaryForm` - `String`	Identifies the item as fiction or nonfiction
`locations` - `[Location!]`	Places associated with item, including location of publication
`notes` - `[Note!]`	Notes about item from source record
`numbering` - `String`
`oclcs` - `[String!]`	Use `identifiers`
`physicalDescription` - `String`	Physical description of item
`placeOfPublication` - `String`	Use `locations`
`publicationDate` - `String`	Use `dates`
`publicationFrequency` - `[String!]`	Publication frequency of item (used for serials)
`publicationInformation` - `[String!]`	Imprint information for item
`relatedItems` - `[RelatedItem!]`	Items that are related to the item in some way
`relatedPlace` - `[String!]`	Use `locations`
`rights` - `[Rights!]`	Rights information for the item
`score` - `String`	Search relevance
`source` - `String!`	Name of source record system
`sourceLink` - `String!`	URL for source record in source system
`subjects` - `[Subject!]`	Subject terms for item
`summary` - `[String!]`	Summary of contents of item (also where abstract goes if applicable)
`timdexRecordId` - `ID!`	TIMDEX unique identifier for the item
`title` - `String!`	Title of item

Example

{
  "alternateTitles": [AlternateTitle],
  "callNumbers": ["xyz789"],
  "citation": "xyz789",
  "contentType": ["abc123"],
  "contents": ["abc123"],
  "contributors": [Contributor],
  "dates": [Date],
  "dois": ["abc123"],
  "edition": "xyz789",
  "fileFormats": ["abc123"],
  "format": ["abc123"],
  "fundingInformation": [Funding],
  "highlight": [Highlight],
  "holdings": [Holding],
  "identifier": 4,
  "identifiers": [Identifer],
  "imprint": ["xyz789"],
  "inBibliography": ["abc123"],
  "isbns": ["abc123"],
  "issns": ["abc123"],
  "languages": ["xyz789"],
  "lccn": "abc123",
  "links": [Link],
  "literaryForm": "abc123",
  "locations": [Location],
  "notes": [Note],
  "numbering": "xyz789",
  "oclcs": ["xyz789"],
  "physicalDescription": "abc123",
  "placeOfPublication": "xyz789",
  "publicationDate": "xyz789",
  "publicationFrequency": ["xyz789"],
  "publicationInformation": ["abc123"],
  "relatedItems": [RelatedItem],
  "relatedPlace": ["abc123"],
  "rights": [Rights],
  "score": "xyz789",
  "source": "abc123",
  "sourceLink": "abc123",
  "subjects": [Subject],
  "summary": ["xyz789"],
  "timdexRecordId": 4,
  "title": "abc123"
}

Types

RelatedItem

Fields

Field Name	Description
`description` - `String`	Description of the related item
`itemType` - `String`	Type of related item
`kind` - `String`	Use `relationship`
`relationship` - `String`	How the item is related
`uri` - `String`	URI for the related item, if applicable
`value` - `[String!]`	Use `description, uri, or item_type`

Example

{
  "description": "xyz789",
  "itemType": "abc123",
  "kind": "abc123",
  "relationship": "xyz789",
  "uri": "abc123",
  "value": ["xyz789"]
}

Types

Rights

Fields

Field Name	Description
`description` - `String`	Description of rights statement
`kind` - `String`	Type of rights statement
`uri` - `String`	Link to additional information about rights statement

Example

{
  "description": "xyz789",
  "kind": "abc123",
  "uri": "abc123"
}

Types

Search

Fields

Field Name	Description
`aggregations` - `Aggregations`
`hits` - `Int!`
`records` - `[Record!]`

Example

{
  "aggregations": Aggregations,
  "hits": 987,
  "records": [Record]
}

Types

String

Description

Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Types

Subject

Fields

Field Name	Description
`kind` - `String`	Type of subject term
`value` - `[String!]`	Value of subject term

Example

{
  "kind": "xyz789",
  "value": ["xyz789"]
}

Types

Version

Fields

Field Name	Description
`distribution` - `String!`
`luceneVersion` - `String!`
`number` - `String!`

Example

{
  "distribution": "xyz789",
  "luceneVersion": "xyz789",
  "number": "abc123"
}

Documentation by Anvil SpectaQL