Confluence Retirement

In an effort to consolidate USGS hosted Wikis, myUSGS’ Confluence service is scheduled for retirement on January 27th, 2023. The official USGS Wiki and collaboration space is now SharePoint. Please migrate existing spaces and content to the SharePoint platform and remove it from Confluence at your earliest convenience. If you need any additional information or have any concerns about this change, please contact Thank you for your prompt attention to this matter.

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents

This documentation explains ScienceBase REST services and ways to interact with the ScienceBase API. The documentation focuses on Item Class and its related objects as they are implemented in the ItemController and ItemsController REST Service end points. Examples for using GET, POST, PUT, UPSERT, and DELETE operations are provided. Documentation is concentrated in 4 areas:  

  1. The Item core objects model - includes information fields used to describe a ScienceBase Item. 

  2.  JSON item example  - JSON view of a ScienceBase item built to completeness using simple example text/files/objects. 

  3. A step-by-step example of using the REST Service Firefox Client to perform a GET, POST, PUT, UPSERT, and DELETE operations.  

  4. More advanced CRUD operations using identifiers, multiple items, async, and downloading links.

HINT: Before you get started with REST Service for an Item, it is helpful to create a test record for reference in JSON format. Go to ScienceBase: to create a new record. Complete requested information in entry tabs. Popup hints demarked by “?” provide information about the sought metadata and preferred format.  These helpful popups describe the fields in detail and match up to the core objects below.  Once an Item is created in ScienceBase, you can select the "view JSON" link (bottom left in item summary page, or append "?format=json" to item URL in the browser web address bar) to view the JSON representation of the ScienceBase Item.

Within the child pages of this page is a more syntactical and robust CRUD operations page along with a bevy of child pages dealing with the more advanced REST operations within ScienceBase. 

Table of Contents

Item Core Objects

Item contains the following core objects:

  • id: ObjectId type that is a system generated unique identifier of an item

  • title: String type, Item Title

  • subTitle: String type, Item Subtitle

  • body: String type, Item Description

  • purpose: String type, Item Purpose

  • rights: String type, Item Rights

  • provenance: ItemProvenance type

    • annotation: String type, ‘Item origin’

    • html: System derived

    • dataSource: System derived

    • dateCreated: System derived

    • lastUpdated: System derived

    • lastUpdatedBy: System derived

    • createdBy: System derived

  • materialRequestInstructions: String type, Item Material Request Instructions

  • alternateTitles: String type, List of Item Alternate Titles

  • contacts: List<Contact>, Item Contact, some of the many sub-fields:

    • name: String type, Contact name (of person or organization)

    • type: String type, Contact type (user entered or drop-down selection)

    • contactType: String type, Contact contact type (person, organization, or blank)

  • tags: List<Tag>

    • name: String type, tag name

    • scheme: String type, tag scheme (url)

    • type: String type, tag type (drop-down selection)

    • vocab: String type, user entered vocabulary

    • label: String type, user entered label

    • uri: String type, (uri)

  • identifiers: List<Identifier>

    • scheme: String type

    • type: String type

    • key: String type

  • facets: List<Facet>, sub-fields not listed here.  Facets can be ingested through the file upload process

  • citation: String type, Citation as in Journal Article, etc.

  • spatial: ItemSpatial type

    • representationalPoint: GIS value

    • representationalPointIsDerived: Boolean (default false)

    • boundingBox:

      • minY: (default null), GIS value

      • maxY: (default null), GIS value

      • minX: (default null), GIS value

      • maxX: (default null), GIS value

  • distributionLinks: List<SB2WebLink>, system derived links (from shapefiles or uploaded files)

    • uri: String type, system derived uri

    • title: String type, system derived title

    • type: String type, system derived type

    • typeLabel: String type, system derived type label

    • rel: String type, system derived relationship

  • dates: List<ItemDate>

    • type: String type, (drop-down selection provided)

    • dateString: String type, use authorized formats

    • label: String type, describe the date

  • files: List<ItemFile>, some of the many sub-fields:

    • name: String type, system derived filename

    • contentType: String type, system derived content type (ex. jpeg/image)

    • pathOnDisk: String type, system derived identifier of where stored

    • url: String type, system derived url of where stored

    • size: String type, system derived size of file in bytes

  • webLinks: List<ItemWebLink>

    • type: String type, system derived

    • typeLabel: String type, (user entered or drop-down selection)

    • title: String type

    • uri: String type

    • rel: String type, system derived relationship

    • contentType: String type, system derived content type (example, jpeg/image)

    • hidden: Boolean type

  • extents: List<Long>, system derived from footprint studio

  • parentId: ObjectId type that is the parent identifier of an item

  • hasChildren: Boolean type

  • browseCategories: Set<String> (tied to tag type), (user entered or drop-down selection)

  • browseTypes: Set<String> (tied to tag type), (user entered or drop-down selection)

  • locked: Boolean type, default false