swagger: "2.0" info: title: Dataverse Metrics API description: An API for Dataverse metrics. (internal use) version: 0.5.0 # the domain of the service host: services.dataverse.harvard.edu # array of all schemes that your API supports schemes: - https # will be prefixed to all paths basePath: /miniverse/metrics/v1 produces: - application/json paths: /dataverses/count: get: summary: Simple count of published Dataverses description: Returns number of published Dataverses tags: - metrics - dataverses parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Number of published Dataverses schema: $ref: "#/definitions/TotalCount" 400: description: Parameter error /dataverses/count/monthly: get: summary: Number of published Dataverses by the month they were created*. (* Not month published) description: Returns a list of counts and cumulative counts of all Dataverses added in a month tags: - metrics - dataverses parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: A list of Dataverse counts by month schema: $ref: "#/definitions/MonthCounts" 400: description: Parameter error /dataverses/count/by-affiliation: get: summary: Number of Dataverses by Affiliation description: Number of Dataverses by Affiliation. tags: - metrics - dataverses parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: Number of published Dataverses by Affiliation. schema: $ref: "#/definitions/AffiliationCounts" 400: description: Parameter error /dataverses/count/by-type: get: summary: Number of Dataverses by Type description: Number of Dataverses by Type. tags: - metrics - dataverses parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/showUncategorizedParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: Number of published Dataverses by Type. schema: $ref: "#/definitions/DataverseTypeCount" 400: description: Parameter error /datasets/count: get: summary: Simple count of published Datasets description: Returns number of published Datasets tags: - metrics - datasets parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Number of published Datasets schema: $ref: "#/definitions/TotalCount" 400: description: Parameter error /datasets/count/monthly: get: summary: Number of published Datasets by the month they were created*. (* Not month published) description: Returns a list of counts and cumulative counts of all datasts added in a month tags: - metrics - datasets parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: A list of Dataset counts by month schema: $ref: "#/definitions/MonthCounts" 400: description: Parameter error /datasets/count/by-subject: get: summary: Number of Datasets by Subject description: Number of Datasets by Subject tags: - metrics - datasets parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: Number of Datasets by Subject schema: $ref: "#/definitions/DatasetSubjectCounts" 400: description: Parameter error /datasets/file-stats: get: summary: Counts of files per Dataset using the latest DatasetVersion description: Counts of files per Dataset using the latest DatasetVersion. Answers the question -> How many datasets have "x" number of files? For example, if the "bin_size" is set to 20, results will show the number of datasets with 0 to 19 files, the number of datasets with 20 to 29 files, etc. tags: - metrics - datasets parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/binSize" - $ref: "#/parameters/skipEmptyBins" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: Counts of files per Dataset using the latest DatasetVersion schema: $ref: "#/definitions/BinCounts" 400: description: Parameter error /datasets/bytes-used: get: summary: Counts of published datasets based on total bytes of storage used description: Counts of datasets based on total bytes of storage used. Answers the question -> How many datasets have "x" number of bytes? For example, if the "bin_size" is set to 52428800, results will show the number of datasets with "0.0 B to 50.0 MB" of data, the number of datasets with "50.0 MB to 100.0 MB", etc. tags: - metrics - datasets parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/binSizeBytes" - $ref: "#/parameters/skipEmptyBins" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: Counts of files per Dataset using the latest DatasetVersion schema: $ref: "#/definitions/BinCountsSizes" 400: description: Parameter error /files/count: get: summary: Simple count of published Files description: Returns number of published Files tags: - metrics - files parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Number of published Files schema: $ref: "#/definitions/TotalCount" 400: description: Parameter error /files/count/monthly: get: summary: Number of Files by the month they were created*. (* Not month published) description: Returns a list of counts and cumulative counts of all Files added in a month tags: - metrics - files parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: A list of File counts by month schema: $ref: "#/definitions/MonthCounts" 400: description: Parameter error /files/downloads/count/monthly: get: summary: Number of downloaded Files by month description: Returns a list of counts and cumulative counts of all Files downloaded in a month. Superuser access required. tags: - metrics - files parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/selectedDataverseAliases" - $ref: "#/parameters/includeChildDataverses" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: A list of file download counts by month. schema: $ref: "#/definitions/MonthCounts" 400: description: Parameter error /files/count/by-type: get: summary: Number of files by content type description: Returns a list of file counts by content type tags: - metrics - files parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/startDateParam" - $ref: "#/parameters/endDateParam" - $ref: "#/parameters/selectedYearParam" - $ref: "#/parameters/publicationStateParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: A list of file counts by content type schema: $ref: "#/definitions/FileTypeCounts" 400: description: Parameter error /files/extensions: get: summary: File extension counts within a given content type. description: File extension counts within a given content type. tags: - metrics - files parameters: - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/contentTypeParam" - $ref: "#/parameters/prettyJSONParam" - $ref: "#/parameters/asCSV" - $ref: "#/parameters/asExcel" responses: 200: description: File extension counts within a given content type. schema: $ref: "#/definitions/FileExtensionCounts" 400: description: Parameter error /dataverses/by-id/{dv_id}: get: summary: Retrieve published Dataverse object in JSON format. description: Retrieve Dataverse object in JSON format. tags: - dataverse/dataset JSON - (unofficial, only published data) parameters: - $ref: "#/parameters/dataverseObjectId" - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Retrieve Dataverse object in JSON format. schema: $ref: "#/definitions/Dataverse" 400: description: Parameter error /dataverses/by-alias/{alias}: get: summary: Retrieve published Dataverse object in JSON format. description: Retrieve Dataverse object in JSON format. tags: - dataverse/dataset JSON - (unofficial, only published data) parameters: - $ref: "#/parameters/dataverseAlias" - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Retrieve Dataverse object in JSON format. schema: $ref: "#/definitions/Dataverse" 400: description: Parameter error /datasets/by-id/{ds_id}: get: summary: Retrieve published Dataset object in JSON format. description: Retrieve published Dataset object in JSON format. tags: - dataverse/dataset JSON - (unofficial, only published data) parameters: - $ref: "#/parameters/datasetId" - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Retrieve published Dataset object in JSON format. schema: $ref: "#/definitions/Dataset" 400: description: Parameter error /datasets/by-persistent-id: get: summary: Retrieve published Dataset object in JSON format. description: Retrieve published Dataset object in JSON format. tags: - dataverse/dataset JSON - (unofficial, only published data) parameters: - $ref: "#/parameters/persistentId" - $ref: "#/parameters/dataverseAPIKey" - $ref: "#/parameters/prettyJSONParam" responses: 200: description: Retrieve published Dataset object in JSON format. schema: $ref: "#/definitions/Dataset" 400: description: Parameter error # ------------------------------ # Define reusable parameters: # ------------------------------ parameters: startDateParam: name: start_date in: query description: Optional. Inclusive start date in YYYY-MM-DD format type: string endDateParam: name: end_date in: query description: Optional. Inclusive end date in YYYY-MM-DD format type: string selectedYearParam: name: selected_year in: query description: Optional. Selected year in YYYY format type: string timeSortParam: name: time_sort in: query description: Optional. Sort by time. 'a' = ascending; 'd' = descending type: string publicationStateParam: name: pub_state in: query description: Optional. Specify whether to include published records, unpublished records, or all. Defaults to "published" type: string enum: - published - unpublished - all prettyJSONParam: name: pretty in: query description: Optional. Returns HTML response showing formatted JSON type: boolean showUncategorizedParam: name: show_uncategorized in: query description: Optional. For Dataverse type counts, show uncategorized Dataverses. type: boolean contentTypeParam: name: ctype in: query description: Optional. Value from the Filemetadata 'contenttype' column. e.g. "application/octet-stream", "data/various-formats", etc type: string dataverseAPIKey: name: key in: query description: Dataverse API key. Required for production use. See http://guides.dataverse.org/en/latest/api/native-api.html type: string selectedDataverseAliases: name: selected_dvs in: query description: Optional. Narrow results by specific Dataverses. Supply Dataverse aliases separated by a comma. e.g. "icraf" By default, doesn't included children. See "include_child_dvs" parameter. The aliases ARE CASE SENSITIVE. type: string includeChildDataverses: name: include_child_dvs in: query description: Optional. When narrowing results by specific Dataverses, include child Dataverses and Datasets. See "selected_dvs" type: boolean asCSV: name: as_csv in: query description: Optional. Return the output in .csv format type: boolean asExcel: name: as_excel in: query description: Optional. Return the output in .xlsx format (Test) type: boolean binSize: name: bin_size in: query description: Optional. Change the binning size. Default is 20. type: integer binSizeBytes: name: bin_size_bytes in: query description: Optional. Change the binning size. Default is 52,428,800 (without the commas) -- 50 MB. type: integer numBins: name: num_bins in: query description: Optional. Set the max number of bins. May cut off last bins. type: integer skipEmptyBins: name: skip_empty_bins in: query description: Optional. Remove bins with a zero count type: boolean dataverseObjectId: name: dv_id in: path description: Dataverse ID required: true type: integer datasetId: name: ds_id in: path description: Dataset ID required: true type: integer persistentId: name: persistentId in: query description: Dataset Persistent ID required: true type: string dataverseAlias: name: alias in: path description: Dataverse Alias required: true type: integer # ------------------------------ # Define response definitions # ------------------------------ definitions: TotalCount: properties: count: type: integer count_string: type: string MonthCount: properties: yyyy_mm: type: string count: type: integer running_total: type: integer year_num: type: integer month_name: type: string month_num: type: integer month_name_short: type: string MonthCounts: type: array items: $ref: "#/definitions/MonthCount" BinCount: properties: bin: type: string count: type: integer bin_start_inclusive: type: integer bin_end: type: integer bin_str: type: string sort_key: type: integer BinCounts: type: array items: $ref: "#/definitions/BinCount" BinCountSize: properties: bin: type: string count: type: integer percentage_of_datasets: type: string bin_start_inclusive: type: integer bin_start_inclusive_comma: type: string bin_start_inclusive_abbrev: type: string bin_end: type: integer bin_end_comma: type: string bin_end_abbrev: type: string bin_str: type: string sort_key: type: integer BinCountsSizes: type: array items: $ref: "#/definitions/BinCountSize" FileExtensionCount: properties: extension: type: string count: type: integer total_count: type: integer percent_string: type: string FileExtensionCounts: type: array items: $ref: "#/definitions/FileExtensionCount" NumberUniqueExtensions: properties: number_unique_extensions: type: integer AffiliationCount: properties: affiliation: type: string affiliation_count: type: integer total_count: type: integer percent_string: type: string AffiliationCounts: type: array items: $ref: "#/definitions/AffiliationCount" DataverseTypeCount: properties: dataversetype: type: string dataversetype_label: type: string type_count: type: integer total_count: type: integer percent_string: type: string DataverseTypeCounts: type: array items: $ref: "#/definitions/DataverseTypeCount" FileTypeCount: properties: contenttype: type: string short_content_type: type: string type_count: type: integer total_count: type: integer percent_string: type: string FileTypeCounts: type: array items: $ref: "#/definitions/FileTypeCount" DatasetSubjectCount: properties: subject: type: string count: type: integer total_count: type: integer percent_string: type: string percent_number: type: number DatasetSubjectCounts: type: array items: $ref: "#/definitions/DatasetSubjectCount" Dataverse: properties: id: type: integer name: type: string alias: type: string dv_link: type: string affiliation: type: 'null' dataversetype: type: string description: type: string publicationInfo: type: object properties: isPublished: type: boolean publicationDate: type: string required: - isPublished - publicationDate contacts: type: array items: type: object properties: email: type: string required: - email creator: type: object properties: useridentifier: type: string email: type: string affiliation: type: string firstname: type: string lastname: type: string required: - useridentifier - email - affiliation - firstname - lastname ownerInfo: type: object properties: ownerId: type: 'null' isRootDataverse: type: boolean required: - ownerId - isRootDataverse isRootDataverse: type: 'null' theme: type: object properties: dataverse: type: integer tagline: type: string logoformat: type: string logoalignment: type: 'null' logobackgroundcolor: type: string linkcolor: type: string backgroundcolor: type: string logo: type: string textcolor: type: string linkurl: type: 'null' id: type: integer required: - dataverse - tagline - logoformat - logoalignment - logobackgroundcolor - linkcolor - backgroundcolor - logo - textcolor - linkurl - id metadatablockroot: type: boolean templateroot: type: boolean permissionroot: type: boolean themeroot: type: boolean facetroot: type: boolean guestbookroot: type: boolean Dataset: properties: title: type: string id: type: integer persistentIdInfo: type: object properties: protocol: type: string authority: type: string identifier: type: string persistentId: type: string persistentUrl: type: string required: - protocol - authority - identifier - persistentId - persistentUrl isPublished: type: boolean timestamps: type: object properties: createdate: type: string publicationdate: type: string required: - createdate - publicationdate semanticVersionInfo: type: object properties: semantic_version: type: string versionNumber: type: integer versionMinorNumber: type: integer versionState: type: string required: - semantic_version - versionNumber - versionMinorNumber - versionState dv_link: type: string metadata_blocks: type: object properties: citation: type: object properties: datasetContact: type: array items: type: object properties: datasetContactName: type: string datasetContactAffiliation: type: string datasetContactEmail: type: string required: - datasetContactName - datasetContactAffiliation - datasetContactEmail author: type: array items: type: object properties: authorName: type: string required: - authorName keyword: type: array items: type: object properties: keywordValue: type: string keywordVocabulary: type: string keywordVocabularyURI: type: string required: - keywordValue - keywordVocabulary - keywordVocabularyURI dsDescription: type: array items: type: object properties: dsDescriptionValue: type: string dsDescriptionDate: type: string required: - dsDescriptionValue - dsDescriptionDate contributor: type: array items: type: object properties: contributorType: type: string contributorName: type: string required: - contributorType - contributorName alternativeTitle: type: string subject: type: array items: type: string depositor: type: string dateOfDeposit: type: string title: type: string required: - datasetContact - author - keyword - dsDescription - contributor - alternativeTitle - subject - depositor - dateOfDeposit - title geospatial: type: object properties: geographicBoundingBox: type: array items: type: object properties: westLongitude: type: string eastLongitude: type: string northLongitude: type: string southLongitude: type: string required: - westLongitude - eastLongitude - northLongitude - southLongitude geographicUnit: type: array items: type: string required: - geographicBoundingBox - geographicUnit required: - citation files: type: array items: type: object properties: id: type: integer datasetVersionId: type: integer name: type: string description: type: string specs: type: object properties: filesystemname: type: string contentType: type: string filesize_bytes: type: integer checksum: type: object properties: value: type: string type: type: string required: - value - type required: - filesystemname - contentType - filesize_bytes - checksum restricted: type: boolean ingeststatus: type: string file_access_url: type: string timestamps: type: object properties: createdate: type: string publicationdate: type: string required: - createdate - publicationdate required: - id - datasetVersionId - name - description - specs - restricted - ingeststatus - file_access_url - timestamps required: - title - id - persistentIdInfo - isPublished - timestamps - semanticVersionInfo - dv_link - metadata_blocks - files