Loading...

API documentation


The purpose of the IAU Office of Astronomy for Education (OAE)'s API is to provide structured access to our database of astronomy education resources. Below we list the different types of resources covered by the API and how to access them. Note all of the pages here use a page size of 100 entries, you can move pages using the page GET parameter. Currently only the English language version of Big Ideas is served by the API.

All of our diagram captions, image captions and glossary terms are available under Creative Commons CC BY-4.0 license please credit these texts to IAU/OAE. You can find the names of the individual translators for captions and diagrams in the pages about each of those captions and diagrams. You can also find our glossary contributors here.

What's in the API?

  • Jump to

  • Activities

    Both available for a list of all and a list with filtering via GET parameters.
    What's included?
    • activity_label: The title of the activity in English
    • activity_slug: A string identifying this activity, common across all translations of this activity
    • activity_title: The title of the activity
    • english_version_doi: The DOI of the English version of this activity
    • glossary_terms: A list of the ID numbers this activity is tagged with
    • categories: A list of the scientific categories/topics this activity is tagged
    • category_ids: A list of the ID numbers for the scientific categories/topics this activity is tagged with
    • big_ideas: The Big Ideas this activity has been tagged with. This number corresponds to the Big Idea number in the most recent version of Big Ideas
    • big_ideas_subidea: The Big Ideas subidea this activity has been tagged with. This number corresponds to the Big Idea subidea number in the most recent version of Big Ideas
    • big_ideas_subidea_ids: The ID number of the Big Ideas subidea
    • areas_of_learning: The areas of learning covered by this activity
    • costs: The financial and material costs to run this activity
    • group_or_individual: If the activity for groups or individuals
    • duration: How long will this activity take?
    • education_levels: What education levels is the activity appropriate for?
    • skills: What skills are learned during this activity.
    • license: The license this activity is published under
    • license_url: A link to the license this activity is published under
    • language_code: The language of the activity listed as a combination of the (represented as a ISO 639 code, mostly ISO 639-1 codes) and if applicable the script code (represented as a four letter ISO 15924 code) and the country code(represented as a ISO 3166-1 alpha_2 code) . So for example Chinese in Simplified Characters is zh-hans and Brazilian Portuguese is pt-br. For a list of these language codes see here.
    • activty_url: A link to the page about this activity on our website
    • teaser: Short teaser text about this activity
    • abstract: A longer abstract about this activity (not available for all activities)
    What can I filter on?
    You can filter on the following using GET parameters.
    • You can select all translations of a particular activity by filtering on that activity's slug. Set slug=
    • You can select activities in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
    • You can select activities tagged with a particular glossary term. Set glossary-term=your_glossary_term_id
    • You can select activities tagged with a particular category. Set category=your_category_id
    • You can select activities tagged with a particular license. Set license=your_license_short_name
    • You can select activities tagged with a particular Big Idea. Set big-idea=your_big_idea_id
    • You can select activities tagged with a particular Big Ideas subidea. Set big-idea=your_subidea_id, here use 2.1 for subidea 1 of big idea 2

  • Big Ideas

    Both available for a list of all and a list with filtering via GET parameters.
    Note only the current version of Big Ideas (version 2) is available via the API.
    What's included?
    • big_idea_number: The number of this Big Idea
    • version_number: The Big Ideas Version this Big Idea comes from
    • headline_in_english: The headline of this Big Idea in English
    • language_code: The language of the Big Idea listed as a combination of the (represented as a ISO 639 code, mostly ISO 639-1 codes) and if applicable the script code (represented as a four letter ISO 15924 code) and the country code(represented as a ISO 3166-1 alpha_2 code) . So for example Chinese in Simplified Characters is zh-hans and Brazilian Portuguese is pt-br. For a list of these language codes see here.
    • headline: The translated headline of this Big Idea
    • number_substitute: If this language doesn't use western Arabic numbers then the number substitute of this Big Idea will be here
    • categories: The scientific categories this Big idea is tagged with
    • category_ids: The ID numbers of the scientific categories this Big idea is tagged with
    • glossary_terms: The ID numbers of the glossary terms that belong to this Big Idea
    • subideas: The subideas of this BigIdea
    • subideas_ids: The ID numbers of the subideas of this BigIdea
    What can I filter on?
    You can filter on the following using GET parameters.
    • You can select all translations of a particular Big Idea using that Big Ideas number.. Set big-idea=your_big_idea_number
    • You can select Big Ideas from a particular version of Big Ideas. Set version=your_version_number
    • You can select Big Ideas in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
    • You can select Big Ideas tagged with a particular category. Set category=your_category_id

  • Big Ideas SubIdeas

    Both available for a list of all and a list with filtering via GET parameters.
    Note only the current version of Big Ideas (version 2) is available via the API.
    What's included?
    • sub_idea_id: The ID number of this SubIdea
    • sub_idea_of: The number of the Big Idea this SubIdea belongs too
    • sub_idea_number: The number of this SubIdea within its Big Idea
    • version_number: The Big Ideas Version this Big Idea comes from
    • headline_in_english: The headline of this SubIdea in English
    • language_code: The language of the SubIdea listed as a combination of the (represented as a ISO 639 code, mostly ISO 639-1 codes) and if applicable the script code (represented as a four letter ISO 15924 code) and the country code(represented as a ISO 3166-1 alpha_2 code) . So for example Chinese in Simplified Characters is zh-hans and Brazilian Portuguese is pt-br. For a list of these language codes see here.
    • headline: The translated headline of this SubIdea
    • text: The translated text of this SubIdea
    • number_substitute: If this language doesn't use western Arabic numbers then the number substitute of this SubIdea will be here
    • categories: The scientific categories this SubIdea is tagged with
    • category_ids: The ID numbers of the scientific categories this SubIdea is tagged with
    • glossary_terms: The ID numbers of the glossary terms that belong to this Big Idea
    • :
    What can I filter on?
    You can filter on the following using GET parameters.
    • You can select all SubIdeas of a particular Big Idea using that Big Ideas number. Set big-idea=your_big_idea_number
    • You can select SubIdeas from a particular version of Big Ideas. Set version=your_version_number
    • You can select SubIdeas in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
    • You can select translations of a particular SubIdea tagged either by setting the number of that SubIdea (subidea=your_subidea_number where SubIdea 10 of Big Idea 2 would be written as 2.10) or by setting the ID number of that SubIdea (subidea_id=your_subidea_id_number).
    • You can select Big Ideas tagged with a particular category. Set category=your_category_id

  • Diagrams

    Both available for a list of all and a list with filtering via GET parameters.
    What's included?
    • diagram_label: The title of the diagram in English
    • diagram_slug: A string identifying this diagram, common across all translations of this diagram
    • diagram_title: The title of the diagram
    • glossary_terms: A list of the ID numbers this diagram is tagged with
    • categories: A list of the scientific categories/topics this diagram is tagged
    • category_ids: A list of the ID numbers for the scientific categories/topics this diagram is tagged with
    • big_ideas: The Big Ideas this diagram has been tagged with. This number corresponds to the Big Idea number in the most recent version of Big Ideas
    • big_ideas_subidea: The Big Ideas subidea this diagram has been tagged with. This number corresponds to the Big Idea subidea number in the most recent version of Big Ideas
    • big_ideas_subidea_ids: The ID number of the Big Ideas subidea this diagram has been tagged with.
    • caption: A caption in this diagram
    • alt_text: Alt text in this diagram
    • credit_text: The credit text for this diagram
    • credit_url: A link to the original source of this diagram file (or a diagram it is based on)
    • generated_from_github_repository: If this diagram was generated using a Github repository it is linked here
    • license: The license this diagram is published under
    • license_url: A link to the license this diagram is published under
    • language: The language of the diagram listed as a combination of the (represented as a ISO 639 code, mostly ISO 639-1 codes) and if applicable the script code (represented as a four letter ISO 15924 code) and the country code(represented as a ISO 3166-1 alpha_2 code) . So for example Chinese in Simplified Characters is zh-hans and Brazilian Portuguese is pt-br. For a list of these language codes see here.
    • multimedia_file: A link to the image file for this diagram
    • pdf_file: A link to the pdf file for this diagram
    • diagram_url: A link to the page about this diagram on our website
    What can I filter on?
    You can filter on the following using GET parameters.
    • You can select all translations of a particular diagram by filtering on that diagram's slug. Set slug=your_slug
    • You can select diagrams in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
    • You can select diagrams tagged with a particular glossary term. Set glossary-term=your_glossary_term_id
    • You can select diagrams tagged with a particular category. Set category=your_category_id
    • You can select diagrams tagged with a particular license. Set license=your_license_short_name
    • You can select diagrams tagged with a particular Big Idea. Set big-idea=your_big_idea_id
    • You can select diagrams tagged with a particular Big Ideas subidea. Set big-idea=your_subidea_id, here use 2.1 for subidea 1 of big idea 2

  • Glossary Terms

    Both available for a list of all and a list with filtering via GET parameters.
    What's included?
    • term_name: The name of this glossary term
    • term_definition: The definition of this glossary term. Null if glossary term is overridden with a link to another term, see override_term_number
    • term_approval_level: The approval level of this glossary term - A approved by research astronomer and teacher, B approved by amateur astronomer and teacher, C not yet approved
    • language_code: The language of the glossary term listed as a combination of the (represented as a ISO 639 code, mostly ISO 639-1 codes) and if applicable the script code (represented as a four letter ISO 15924 code) and the country code(represented as a ISO 3166-1 alpha_2 code) . So for example Chinese in Simplified Characters is zh-hans and Brazilian Portuguese is pt-br. For a list of these language codes see here.
    • term_number: The number of this term (common across all translations of this term).
    • term_in_english: The term in English
    • based_on_current_english_version: Is this translation based on the current English translation? (null for the English version).
    • linked_terms: The ID numbers of linked glossary terms
    • alternate_terms: Alternative names for this term
    • override_term_number: Does this term redirect to another term? Sometimes terms don't have a definition and just redirect to another term. For example all lunar phases redirect to the term lunar phase.
      • categories: A list of the scientific categories/topics this glossary term is tagged
    • category_ids: A list of the ID numbers for the scientific categories/topics this glossary term is tagged with
    • override_url: A link to the term this term redirects to
    • url: A link to the webpage for this glossary term
    What can I filter on?
    You can filter on the following using GET parameters.
    • You can select all translations of a particular glossary term by filtering on that glossary term's id number. Set term-number=your_term_number
    • You can select glossary terms in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
    • You can select terms that are linked (not redirected) to another term. Set linked-to-term=your_linked_to_term_id
    • You can select activities tagged with a particular category. Set category=your_category_id

  • Media Files

    Both available for a list of all and a list with filtering via GET parameters.

    Media files consist of images, videos, audio files or 3D printer files.
    What's included?

    • file_title: The title of the media file
    • record_url: A link to the page about this media file on our website
    • file_url: A link to the media file itself
    • file_additional_format_file: If this file is available in another format it will be linked here
    • doi:The Digital Object Identifier of the media file
    • credit_url: A link to the original source of this media file
    • license: The license this media file is published under
    • license_url: A link to the license this media file is published under
    • media_file_language: If this media file is in a specific language it is listed here (represented as a ISO 639 code, mostly ISO 639-1 codes)
    • media_file_script If this media file is in a specific script or writing system (represented as a four letter ISO 15924 code) it is listed here
    • media_file_language_country If this media file is in a country-specific version or dialect of a language that country (represented as a ISO 3166-1 alpha_2 code) is listed here
    • glossary_terms: A list of the ID numbers this media file is tagged with
    • categories: A list of the scientific categories/topics this media file is tagged
    • category_ids: A list of the ID numbers for the scientific categories/topics this media file is tagged with
    • big_ideas: The Big Ideas this media file has been tagged with. This number corresponds to the Big Idea number in the most recent version of Big Ideas
    • big_ideas_subidea: The Big Ideas subideas this media file has been tagged with. This number corresponds to the Big Idea subidea number in the most recent version of Big Ideas
    • big_ideas_subidea_ids: The ID numbers of the Big Ideas subideas this media file has been tagged with.
    • captions: The captions for this media file. Each caption has:
      • language_code: The language code for this caption. For a list of these language codes see here.
      • file_title: The translated file title in this language
      • short_caption: A short caption in this language
      • caption: A caption in this language
      • alt_text: Alt text in this language
      • credit: The credit for this media file in this language
      • You can select all translations of a particular media file by filtering on that diagram's slug. Set slug=your_slug
      • You can select media files with captions in a particular language. Set language=your_language_code, note for some languages this code will include the writing system and/or country code.
      • You can select media files tagged with a particular glossary term. Set glossary-term=your_glossary_term_id
      • You can select media files tagged with a particular category. Set category=your_category_id
      • You can select media files tagged with a particular license. Set license=your_license_short_name
      • You can select media files tagged with a particular Big Idea. Set big-idea=your_big_idea_id
      • You can select media files tagged with a particular Big Ideas subidea. Set big-idea=your_subidea_id, here use 2.1 for subidea 1 of big idea 2
      • You can select media files of a particular file type. Set file-type=. The options are:
        • img: Image
        • vid: Video
        • snd: Sound
        • p3d: 3D printer files

    What's not in the API?

    • Documents

    • OAE Reviews

    • Scientific Categories/Topics

    What languages are in the API

    For activities, diagrams, glossary terms and multimedia captions we use one combined code that for some languages includes information on script and country variation. Multimedia files themselves can be tagged with language, script and country variation but few are (most are images or videos with no text or speech), where they are the language, script and country variation are separate and follow the relevant ISO standards. Note Traditional Chinese is an automated transliteration from Simplified Chinese.
    Code
    Language

    ar
    Arabic

    bn
    Bengali

    de
    German

    en
    English

    es
    Spanish

    fa
    Persian

    fr
    French

    he
    Hebrew

    hi
    Hindi

    hu
    Hungarian

    id
    Indonesian

    it
    Italian

    ja
    Japanese

    ko
    Korean

    mr
    Marathi

    ne
    Nepali

    pt-br
    Brazilian Portuguese

    pt-pt
    Portuguese

    ro
    Romanian

    zh-hans
    Simplified Chinese

    zh-hant
    Traditional Chinese

    Share on:
    Share on Bluesky   Share on Facebook   Share on Twitter   Share on Whatsapp   Share on LinkedIn   Share by Email

The Office of Astronomy for Education is hosted by the Haus der Astronomie on the campus of the Max Planck Institute for Astronomy in Heidelberg. The Office of Astronomy for Education is an office of the International Astronomical Union, with substantial funding from the Klaus Tschira Foundation and the Carl Zeiss Foundation. The Shaw-IAU Workshops on Astronomy for Education
are funded by the Shaw Prize Foundation.