API Documentation version 2


A brief documentation page for a JSON Web API for developers.



Space Telescope News Releases


List of news releases

      List of published releases, produced by the Office of Public Outreach of the Space Telescope Science Institute.
      All those news releases are present at HubbleSite's news center, at http://hubblesite.org/news.

      They are sorted by the publication date and time (the last release will be the first).

      Format:

        /api/v2/news

      Additional (optional) parameters:
    
Parameter Type Default Description
page Integer or String 1 The possible values are any integer 1 or larger, or 'all' to return all items.
Any other values will default to '1'.
Unless the value passed is 'all', it returns 25 items.
      It returns:
    
key Description
news_idInternal key to identify the release. It can be used to gather more information using the details API call (below).
nameTitle of the News Release
urlhttp://hubblesite.org URL of the news release
      Examples:

        /api/v2/news
        /api/v2/news?page=2
        /api/v2/news?page=all
    

Details of a news release

      Format:

        /api/v2/news_release/:which

      Parameters:
    
Parameter Type Default Description
:which Integer or String (none, required) Possible values
  • 'last', the last news release published
  • 'first', the first news release published
  • The release identifier, in the format YYYY-NN, unique for news release
      It returns:
    
key Description
nameTitle of the News Release
news_idInternal key to identify the release. It can be used to gather more information using the details API call (below).
urlhttp://hubblesite.org URL of the news release
publicationPublication date and time
abstractStory's abstract text (HTML in some cases)
creditsStory's credits and acknowledgments (usually includes HTML tags)
thumbnailHTTPS URL of a thumbnail image, 200x200 pixels.
thumbnail_retinaHTTPS URL of a thumbnail image, 400x400 pixels.
release_imagesArray of integers which identify ids of related images. With those image_ids, it can be gathered more information using the image API call (below)
release_videosArray of integers which identify ids of related videos. With those video_ids, it can be gathered more information using the video API call (below)
      Examples:

        /api/v2/news_release/last
        /api/v2/news_release/2016-29
        /api/v2/news_release/first
    

Images


List of images

      Same as for news releases, the images are sorted by the publication date and time (last goes first).

      Format:

        /api/v2/images
        /api/v2/images/:collection_name

      Parameters:
    
Parameter Type Default Description
:collection_name String science If a collection is specified, it shows the images for that collection.
Collections are sets of images, for example, for Hubble we have collections with the names 'news', 'spacecraft', 'printshop', etc.
Different missions (hubble, james_webb) may have images in different collections.
A possible collection_name is also 'all', which will return all the images for all the collections and missions.
If 'all 'is used for the collection_name, then the mission and collection will be returned for each item.
if collection_name is not 'all', the images' mission will correspond to the site used - hubble's images for hubblesite.org (and media.stsci.edu), and james_webb images for webbtelescope.org.
If not collection is given, the default collection will be used, and if no default exists, all will be used.
page Integer or String 1 The possible values are any integer 1 or larger, or 'all' to return all items.
Any other values will default to '1'.
Unless the value passed is 'all', it returns 25 items.
      It returns:
    
key Description
idInternal key to identify the image. It can be used to gather more information using the details API call (below).
nameName given to the Image
news_nameLegacy name given to this image in a news release. Usually is 'a', 'b', 'c', ...
collectionCollection name the image belongs to.
missionSpace Telescope or telescope website, the image belongs to. It is usually 'hubble', 'james_webb', etc.
      Examples:

        /api/v2/images
        /api/v2/images/all
        /api/v2/images/all?page=2
        /api/v2/images/news
        /api/v2/images/spacecraft?page=all
        /api/v2/images/unknown
    

Image Details

      Format:

        /api/v2/image/:image_id

      Parameters:
    
Parameter Type Default Description
:image_id Integer (none, required) Internal key to identify the image.
      It returns:
    
key Description
nameTitle given to the Image
descriptionImage description text, caption
creditsImage's credits and acknowledgments
news_nameLegacy name given to this Image in a news release. Usually is 'a', 'b', 'c', ...
missionSpace Telescope or telescope website, the Image belongs to. It is usually 'hubble', 'james_webb', etc.
collectionCollection name the Image belongs to.
image_files Array of downloadable image files. It could be images, PDFs, ZIP files containing images, etc. Each element containing:
  • file_url: HTTPS URL of the image file.
  • file_size: Size of the file.
  • width: Width of the image, if it is a common image file format
  • height: Height of the image, if it is an image file
      Example:

        /api/v2/image/200
    

Videos


Videos Lists

      Same as for news releases, the videos are sorted by the publication date and time (last goes first).

      Format:

        /api/v2/videos
        /api/v2/videos/:collection_name

      Parameters:
    
Parameter Type Default Description
:collection_name String science If a collection is specified, it shows the videos for that collection.
Collections are sets of videos, for example, for Hubble we have collections with the names 'news', 'science', 'tonights_sky', etc.
Different missions (hubble, james_webb) may have videos in different collections.
A possible collection_name is also 'all', which will return all the videos for all the collections and missions.
If 'all 'is used for the collection_name, then the mission and collection will be returned for each item.
if collection_name is not 'all', the videos' mission will correspond to the site used - hubble's videos for hubblesite.org (and media.stsci.edu), and james_webb videos for webbtelescope.org.
If not collection is given, the default collection will be used, and if no default exists, all will be used.
page Integer or String 1 The possible values are any integer 1 or larger, or 'all' to return all items.
Any other values will default to '1'.
Unless the value passed is 'all', it returns 25 items.
      It returns:
    
key Description
idInternal key to identify the Video. It can be used to gather more information using the details API call (below).
nameName given to the Video
news_nameLegacy name given to this Video in a news release. Usually is 'a', 'b', 'c', ...
imageHTTPS URL of a thumbnail image, 210x119 pixels.
collectionCollection name the Video belongs to.
missionSpace Telescope or telescope website, the Video belongs to. It is usually 'hubble', 'james_webb', etc.
      Examples:

        /api/v2/videos
        /api/v2/videos/all
        /api/v2/videos/all?page=2
        /api/v2/videos/news
        /api/v2/videos/science?page=all
        /api/v2/videos/unknown
    

Video Details

      Format:

        /api/v2/video/:video_id

      Parameters:
    
Parameter Type Default Description
:video_id Integer (none, required) Internal key to identify the Video.
      It returns:
    
key Description
nameTitle given to the Video
short_descriptionVideo description text, short version.
youtube_idUnique id used by youtube.com, if the video has been uploaded to YouTube. The YouTube URI can be composed based on this id.
teachertube_idUnique id used by teachertube.com, if the video has been uploaded to TeacherTube. usually used for educative material.
creditsVideo's credits and acknowledgments
news_nameLegacy name given to this Video in a news release. Usually is 'a', 'b', 'c', ...
missionSpace Telescope or telescope website, the Video belongs to. It is usually 'hubble', 'james_webb', etc.
collectionCollection name the Video belongs to.
imageHTTPS URL of a thumbnail image, 210x119 pixels.
image_retinaHTTPS URL of a thumbnail image, 420x238 pixels.
html_5_video If the video is set to be displayed as an HTML5 video, this has two components:
  • video_url: HTTPS URL of the Video file.
  • poster_url: HTTPS URL of an image to display in the video player. Sometimes it is the first frame of the Video.
video_files Array of downloadable video files. Each element containing:
  • file_url: HTTPS URL of the video file.
  • file_size: Size of the file.
  • width: Width of the video
  • height: Height of the video
  • frame_rate: Frame rate of the video, usually in frames per second
  • format: Name for the format of the video file
      Example:

      /api/v2/video/500
    

Miscellaneous


Glossary of Astronomy terms

      Format:

        /api/v2/glossary'
    
      Optional parameters:
    
Parameter Type Default Description
page Integer or String 1 The possible values are any integer 1 or larger, or 'all' to return all items.
Any other values will default to '1'.
Unless the value passed is 'all', it returns 25 items.
      It returns:
    
key Description
nameGlossary term
definitionDefinition text.
      Examples:

        /api/v2/glossary
        /api/v2/glossary?page=2
        /api/v2/glossary?page=all
    

Glossary Terms

      Format:

        /api/v2/glossary/:term'
    
      Parameters:
    
Parameter Type Default Description
:term String (none, required) Astronomy term, not case-sensitive, and replacing spaces by underscores.
      It returns:
    
key Description
definitionDefinition text.
      Examples:

        /api/v2/glossary/asteroid
        /api/v2/glossary/elliptical_Galaxy
        /api/v2/glossary/planet
    

Related News RSS Feeds

We are compiling a few RSS news feeds.
      Format:

        /api/v2/external_feed/:feed_name'

      Parameters:
    
Parameter Type Default Description
:feed_name String (none, required) Internal name of the feed. See examples below
page Integer or String 1 The possible values are any integer 1 or larger, or 'all' to return all items.
Any other values will default to '1'.
Unless the value passed is 'all', it returns 25 items.
sort String -pub_date Order of the feed posts, only by publication date (pub_date). The possible values are:
  • pub_date: ascending order (older to newer)
  • -pub_date: descending order (newer to older)
      It returns:

        An array of feed posts.
      
key Description
titlePost title
pub_dateDate and time of publication, as set in the RSS post.
descriptionDescription (text).
linkURL to the feed's site, which can have additional information.
imageHTTPS URL to a copy of the original image included in the post. The next images are generated based on this image
image_squareHTTPS URL to an image generated based in the image posted, at 320x320 pixels (it could have been cropped, reduced or enlarged).
image_square_largeHTTPS URL to an image generated from the image posted, at 640x640 pixels.
thumbnailHTTPS URL to an image generated from the image posted, at 200x125 pixels.
thumbnail_largeHTTPS URL to an image generated from the image posted, at 400x250 pixels.
      Examples:

        European Space Agency RSS Feed:
                   /api/v2/external_feed/esa_feed
                   /api/v2/external_feed/esa_feed?page=2
                   /api/v2/external_feed/esa_feed?sort=pub_date
                   /api/v2/external_feed/esa_feed?page=all
                   /api/v2/external_feed/esa_feed?page=all&sort=pub_date

        James Webb Space Telescope RSS Feed:
                   /api/v2/external_feed/jwst_feed
                   /api/v2/external_feed/jwst_feed?page=2
                   /api/v2/external_feed/jwst_feed?page=2&sort=pub_date
                   /api/v2/external_feed/jwst_feed?page=all
                   /api/v2/external_feed/jwst_feed?page=all&sort=pub_date
    

Common Usage Notes


This Web API is present in both:


The links to news release pages use HTTP only, for now, as hubblesite.org uses only HTTP. We hope to be able to use HTTPS for those links when hubblesite.org starts to use HTTPS.

Common to all the API calls:


For API versioning we will use a simplified variation of Semantic Versioning. We will only bump up the version number (an integer) if we introduce changes that break existing behavior. Otherwise the version will stay the same.

We will try to maintain older versions.