├── .gitignore ├── assets ├── ll2_230.png ├── tsd_cover.png ├── ll2_poster.png ├── repo_poster.png ├── snapi_poster.png ├── ll2_historic_launches.png ├── badge_snapi_website.svg ├── badge_snapi_doc.svg └── badge_tsd_website.svg ├── .github └── FUNDING.yml ├── faqs ├── README.md ├── faq_SNAPI.md ├── faq_TSD.md └── faq_LL2.md ├── tutorials ├── README.md ├── getting_started_SNAPI │ └── README.md ├── getting_started_LL2 │ ├── README.md │ └── launches_past_month.py └── SNAPI_v4_migration │ └── README.md ├── README.md └── announcements └── LL_230_changelog.md /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | -------------------------------------------------------------------------------- /assets/ll2_230.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/ll2_230.png -------------------------------------------------------------------------------- /assets/tsd_cover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/tsd_cover.png -------------------------------------------------------------------------------- /assets/ll2_poster.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/ll2_poster.png -------------------------------------------------------------------------------- /assets/repo_poster.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/repo_poster.png -------------------------------------------------------------------------------- /assets/snapi_poster.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/snapi_poster.png -------------------------------------------------------------------------------- /assets/ll2_historic_launches.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/HEAD/assets/ll2_historic_launches.png -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | patreon: TheSpaceDevs 3 | custom: ["https://www.paypal.com/donate/?hosted_button_id=UCPX4EL6E9JFA", "https://www.paypal.com/donate/?hosted_button_id=5S7MGGWJJBHL6"] 4 | 5 | -------------------------------------------------------------------------------- /faqs/README.md: -------------------------------------------------------------------------------- 1 | # FAQs Contribution Guide 2 | 3 | FAQs are handled directly by the TSD staff. If you see a mistake, typo, or something that needs to be updated, please 4 | contact the TSD staff or open a PR with the suggested changes. 5 | 6 | **If you are looking for a list of available FAQs, check the main table of 7 | contents [here](../README.md#table-of-contents).** 8 | 9 | -------------------------------------------------------------------------------- /tutorials/README.md: -------------------------------------------------------------------------------- 1 | # Tutorials Contribution Guide 2 | 3 | **If you are looking for a list of available tutorials, check the main table of 4 | contents [here](../README.md#table-of-contents).** 5 | 6 | To contribute to existing tutorials, you can either contact the writer with proposed changes or open a PR which will be reviewed by the TSD staff. 7 | 8 | If you want to create a new tutorial, suggest the idea to the TSD staff. If accepted, you can open a PR when it is done and it will be reviewed by the TSD staff. 9 | -------------------------------------------------------------------------------- /tutorials/getting_started_SNAPI/README.md: -------------------------------------------------------------------------------- 1 | # Getting started with the Spaceflight News API 2 | 3 | ## Introduction 4 | The Spaceflight News API (SNAPI for short) enables you to request space related news articles, blogs, and reports. 5 | A full list of features can be found [here](https://thespacedevs.com/snapi). 6 | 7 | To get you started with the API, this tutorial contains some introduction information together with code examples. 8 | For more detailed documentation on all the endpoints, please refer to the [documentation](https://api.spaceflightnewsapi.net/v4/docs). 9 | 10 | ## Quickstart 11 | 12 | To query data, endpoint URLs are used. 13 | Filters and search terms can be added to these. 14 | 15 | Querying the articles endpoint: https://api.spaceflightnewsapi.net/v4/articles 16 | 17 | Adding filters is done by adding them to the base url. See the full list of filters in the [documentation](https://api.spaceflightnewsapi.net/v4/docs). 18 | 19 | 20 | ## Examples 21 | 22 | ### Querying & filtering news articles in Python 23 | 24 | > Filtering 25 | 26 | You can filter on various properties, for example on the news site that published the article. For example get all the articles published by NASA: 27 | ```shell 28 | curl https://api.spaceflightnewsapi.net/v4/articles?news_site=NASA 29 | ``` 30 | 31 | Or maybe you'll want all the articles related to the Artemis I launch: 32 | ```shell 33 | curl https://api.spaceflightnewsapi.net/v4/articles?launch=65896761-b6ca-4df3-9699-e077a360c52a 34 | ``` 35 | 36 | > Limiting 37 | 38 | By default, you'll get 10 articles in the response. You can change this with the `?limit` query parameter: 39 | ```shell 40 | curl https://api.spaceflightnewsapi.net/v4/articles?limit=3 41 | ``` 42 | 43 | > Paginating through all the results 44 | 45 | With the `next` key you can paginate through all the results of your query: 46 | ```python 47 | next_url = "https://api.spaceflightnewsapi.net/v4/articles?launch=65896761-b6ca-4df3-9699-e077a360c52a" 48 | while next_url: 49 | # Requesting next data 50 | next_results = requests.get(next_url).json() 51 | print(next_results) 52 | 53 | # Adding to the original results dictionary 54 | results['results'] += next_results['results'] 55 | 56 | # Updating the next URL 57 | next_url = next_results['next'] 58 | ``` 59 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Repository Poster](assets/repo_poster.png) 2 | 3 | [![Website](https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/e36b2c250ce7fcd4a801c1ed6cb1f9f9d031696b/assets/badge_tsd_website.svg)](https://thespacedevs.com/) 4 | [![Discord](https://img.shields.io/badge/Discord-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/p7ntkNA) 5 | [![Twitter](https://img.shields.io/badge/Twitter-%231DA1F2.svg?style=for-the-badge&logo=Twitter&logoColor=white)](https://twitter.com/TheSpaceDevs) 6 | [![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/TheSpaceDevs) 7 | [![PayPal USD](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white&label=USD)](https://www.paypal.com/donate/?hosted_button_id=UCPX4EL6E9JFA) 8 | [![PayPal EUR](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white&label=EUR)](https://www.paypal.com/donate/?hosted_button_id=5S7MGGWJJBHL6) 9 | 10 | # The Space Devs - FAQs & Tutorials 11 | 12 | This repository contains FAQs (Frequently Asked Questions) related to The Space Devs, our Launch Library 2 and 13 | Spaceflight News APIs as well as tutorials to help get you started with your project. 14 | 15 | If you have any question, feedback, or want to interact with the staff and community, join our [Discord server](https://discord.gg/p7ntkNA). 16 | 17 | ## Table of Contents 18 | 19 | 20 | 21 | * Frequently Asked Questions (FAQs) 22 | * [The Space Devs](faqs/faq_TSD.md) 23 | * [Launch Library 2](faqs/faq_LL2.md) 24 | * [Spaceflight News API](faqs/faq_SNAPI.md) 25 | * Announcements 26 | * [Launch Library 2.3.0 Release](announcements/LL_230_changelog.md) 27 | * Tutorials 28 | * [Contributing](tutorials/README.md) 29 | * Getting started 30 | * [Launch Library 2](tutorials/getting_started_LL2/README.md) 31 | * [Spaceflight News API](tutorials/getting_started_SNAPI/README.md) 32 | * API Migrations 33 | * [Migrating to SNAPI v4](tutorials/SNAPI_v4_migration/README.md) 34 | * Process and visualize data 35 | * [Coming soon™] Process and make statistics with LL2 data 36 | * [Coming soon™] Process and visualize launch telemetry with LDAPI 37 | * Develop basic services 38 | * [Coming soon™] Create a Discord bot that uses LL2 and SNAPI 39 | * [Coming soon™] Create an iOS app that uses LL2 and SNAPI 40 | * [Coming soon™] Use OpenAPI Generator with LL2 41 | 42 | 43 | 44 | -------------------------------------------------------------------------------- /tutorials/getting_started_LL2/README.md: -------------------------------------------------------------------------------- 1 | # Getting started with Launch Library 2 2 | 3 | ## Introduction 4 | The Launch Library 2 API (LL2 for short) enables you to request space related data such as launches, astronauts, etc. 5 | A full list of features can be found [here](https://thespacedevs.com/llapi). 6 | 7 | To get you started with the API, this tutorial contains some introduction information together with code examples. 8 | For more detailed documentation on all the endpoints, please refer to the [documentation](https://ll.thespacedevs.com/docs/). 9 | 10 | Since the production API `ll` has [rate limits](../../faqs/faq_LL2.md#free-and-paid-access), the [development API](../../faqs/faq_LL2.md#what-is-lldev) `lldev` will be used in this tutorial, however this should only by used for development. 11 | 12 | ## Quickstart 13 | 14 | To query data, endpoint URLs are used. 15 | Filters and search terms can be added to these. 16 | 17 | Querying the upcoming launch endpoint: https://lldev.thespacedevs.com/2.3.0/launches/upcoming/ 18 | 19 | Adding filters is done by adding them to the base url. 20 | 21 | 22 | ## Examples 23 | 24 | ### Querying & filtering past launches in Python 25 | 26 | > Filtering 27 | 28 | Here two filters are added, a minimum and maximum date and time to get the launches between the two. 29 | 30 | The time frame of the minimum and maximum are a month ago and now. 31 | The filtered variable is `net`, which represents the launch datetime. 32 | 33 | To filter `net` we add two underscores `__` and the filter terms `gte` (greater-than-or-equal) and `lte` (less-than-or-equal). 34 | Combining these two filters is done using the ampersand symbol `&`. 35 | 36 | Before adding these filters a question mark `?` is added after the base url to indicate the start of parameters. 37 | Then the filter parameter name is given with an equals sign `=` with the value following it. 38 | 39 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L7-L12 40 | 41 | > Setting response mode 42 | 43 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L23-L24 44 | 45 | > Limiting 46 | 47 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L26-L27 48 | 49 | > Ordering 50 | 51 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L29-L30 52 | 53 | > Assembling query URL 54 | 55 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L32-L36 56 | 57 | > Paginating through all the results 58 | 59 | https://github.com/TheSpaceDevs/Tutorials/blob/1b1a40a64b18f7d0ab5d0131189d038fd542b7a9/tutorials/getting_started_LL2/launches_past_month.py#L91-L110 60 | -------------------------------------------------------------------------------- /tutorials/getting_started_LL2/launches_past_month.py: -------------------------------------------------------------------------------- 1 | from datetime import datetime, timedelta 2 | import requests 3 | 4 | # URL 5 | launch_base_url = 'https://lldev.thespacedevs.com/2.3.0/launches/' 6 | 7 | # Time frame: now - 31 days ago 8 | now = datetime.now() 9 | month_ago = now - timedelta(days=31) 10 | 11 | # Adding the time frame to the filters 12 | net_filters = f'net__gte={month_ago.isoformat()}&net__lte={now.isoformat()}' 13 | # Only SpaceX as the launch service provider 14 | lsp_filter = 'lsp__id=121' 15 | # No suborbital launches 16 | orbital_filter = 'include_suborbital=false' 17 | 18 | # Combine filters 19 | filters = '&'.join( 20 | (net_filters, lsp_filter, orbital_filter) 21 | ) 22 | 23 | # Set mode to detailed to include all related objects 24 | mode = 'mode=detailed' 25 | 26 | # Limit returned results to just 2 per query 27 | limit = 'limit=2' 28 | 29 | # Ordering the results by ascending T-0 (NET) 30 | ordering = 'ordering=net' 31 | 32 | # Assemble the query URL 33 | query_url = launch_base_url + '?' + '&'.join( 34 | (filters, mode, limit, ordering) 35 | ) 36 | print(f'query URL: {query_url}') 37 | 38 | # Function to handle requesting data 39 | def get_results(query_url: str) -> dict | None: 40 | """ 41 | Requests data using 42 | the request GET method. 43 | 44 | Parameters 45 | ---------- 46 | quer_url : str 47 | URL to query. 48 | 49 | Returns 50 | ------- 51 | results : dict or None 52 | Results from the query. 53 | 54 | Notes 55 | ----- 56 | Prints exceptions instead of 57 | raising them as this is script 58 | is only meant as a tutorial. 59 | """ 60 | try: 61 | # Requesting data 62 | results = requests.get(query_url) 63 | except Exception as e: 64 | # Print exception when it occurs 65 | print(f'Exception: {e}') 66 | else: 67 | # Checking status of the query 68 | status = results.status_code 69 | print(f'Status code: {status}') 70 | 71 | # Return when the query status isn't 200 OK 72 | # See: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes 73 | if status != 200: 74 | return 75 | 76 | # Converting to JSON and returning 77 | return results.json() 78 | 79 | # Perform first query 80 | results = get_results(query_url) 81 | 82 | # Checking if it was succesful 83 | if not results: 84 | # Quitting the program as an example 85 | # use your own error handling here 86 | quit() 87 | 88 | # Printing resulting dictionary 89 | print(results) 90 | 91 | # Paginating through all the results 92 | next_url = results['next'] 93 | while next_url: 94 | # Requesting next data 95 | next_results = get_results(next_url) 96 | 97 | # Checking if it was succesful 98 | if not results: 99 | # Quitting the program as an example 100 | # use your own error handling here 101 | quit() 102 | 103 | # Printing next results 104 | print(next_results) 105 | 106 | # Adding to the original results dictionary 107 | results['results'] += next_results['results'] 108 | 109 | # Updating the next URL 110 | next_url = next_results['next'] 111 | 112 | print('Done!') 113 | -------------------------------------------------------------------------------- /tutorials/SNAPI_v4_migration/README.md: -------------------------------------------------------------------------------- 1 | # Migrating to SNAPI v4 2 | 3 | With the release of SNAPI v4 a couple of changes are necessary. Although not many or big changes, it's nice to know what 4 | to do when you're planning to move from v3 to v4. This is not a complete list of changes, but it should help you get started. 5 | 6 | ## Response 7 | 8 | In terms of response, not that much has changed: 9 | 10 | **v3 response** 11 | 12 | ```json 13 | [ 14 | { 15 | "id": 18882, 16 | "title": "EGS launch team looking forward to working with Artemis II crew", 17 | "url": "https://www.nasaspaceflight.com/2023/04/egs-launch-team-artemis-ii/", 18 | "imageUrl": "https://www.nasaspaceflight.com/wp-content/uploads/2023/04/52790060302_221dc6d2af_k-1170x803.jpg", 19 | "newsSite": "NASASpaceflight", 20 | "summary": "NASA Exploration Ground Systems (EGS) have been preparing and planning for the Artemis II launch since before the flight crew was announced on April 3. Teams at the Kennedy Space Center (KSC) in Florida are looking forward to working closely with the four astronauts who will be the first to fly to the Moon in over 50 years.", 21 | "publishedAt": "2023-04-04T15:10:47.000Z", 22 | "updatedAt": "2023-04-04T16:32:47.052Z", 23 | "featured": false, 24 | "launches": [ 25 | { 26 | "id": "41699701-2ef4-4b0c-ac9d-6757820cde87", 27 | "provider": "Launch Library 2" 28 | } 29 | ], 30 | "events": [] 31 | } 32 | ] 33 | ``` 34 | 35 | **v4 response** 36 | 37 | ```json 38 | { 39 | "count": 16199, 40 | "next": "https://api.spaceflightnewsapi.net/v4/articles/?limit=10&offset=10", 41 | "previous": null, 42 | "results": [ 43 | { 44 | "id": 18882, 45 | "title": "EGS launch team looking forward to working with Artemis II crew", 46 | "url": "https://www.nasaspaceflight.com/2023/04/egs-launch-team-artemis-ii/", 47 | "image_url": "https://www.nasaspaceflight.com/wp-content/uploads/2023/04/52790060302_221dc6d2af_k-1170x803.jpg", 48 | "news_site": "NASASpaceflight", 49 | "summary": "NASA Exploration Ground Systems (EGS) have been preparing and planning for the Artemis II launch since before the flight crew was announced on April 3. Teams at the Kennedy Space Center (KSC) in Florida are looking forward to working closely with the four astronauts who will be the first to fly to the Moon in over 50 years.", 50 | "published_at": "2023-04-04T17:10:47+02:00", 51 | "updated_at": "2023-04-04T18:32:47.052000+02:00", 52 | "featured": false, 53 | "launches": [ 54 | { 55 | "launch_id": "41699701-2ef4-4b0c-ac9d-6757820cde87", 56 | "provider": "Launch Library 2" 57 | } 58 | ], 59 | "events": [] 60 | } 61 | ] 62 | } 63 | ``` 64 | 65 | The list with articles is now returned as `results`, comparable with the Launch Library 2 response. The response now also 66 | includes meta information about the numbers of articles in the database and a shortcut links to help you with pagination 67 | for example. 68 | 69 | ## Attributes 70 | 71 | In terms of article attributes, keys that consist of multiple words are represented in snake_case. 72 | 73 | ## Documentation 74 | 75 | Documentation is available at https://api.spaceflightnewsapi.net/v4/docs/. The OpenAPI json is downloadable, so 76 | you can use frameworks like the [openapi generator](https://openapi-generator.tech/). 77 | 78 | ## Examples (Python) 79 | ### Getting a list of all articles 80 | 81 | **v3** 82 | ```python 83 | import requests 84 | 85 | articles = requests.get( 86 | "https://api.spaceflightnewsapi.net/v3/articles/").json() 87 | print(articles) 88 | ``` 89 | 90 | **v4** 91 | ```python 92 | import requests 93 | 94 | response = requests.get( 95 | "https://api.spaceflightnewsapi.net/v4/articles/").json() 96 | print(response["results"]) 97 | ``` 98 | 99 | ### Searching 100 | **v3** 101 | ```python 102 | import requests 103 | 104 | articles = requests.get( 105 | "https://api.spaceflightnewsapi.net/v3/articles?title_contains=nasa").json() 106 | print(articles) 107 | ``` 108 | 109 | **v4** 110 | ```python 111 | import requests 112 | 113 | # Here we demo title, but this can also be done with summary. 114 | response_contains = requests.get( 115 | "https://api.spaceflightnewsapi.net/v4/articles?title_contains='nasa launches sls'").json() 116 | print(response["response_contains"]) 117 | 118 | response_contains_all = requests.get( 119 | "https://api.spaceflightnewsapi.net/v4/articles?title_contains_all='nasa, dragon, spacex'").json() 120 | print(response["response_contains_all"]) 121 | 122 | response_contains_one = requests.get( 123 | "https://api.spaceflightnewsapi.net/v4/articles?title_contains_one='nasa, dragon, spacex'").json() 124 | 125 | response_search = requests.get( 126 | "https://api.spaceflightnewsapi.net/v4/articles?search=somerandomsearchphrase").json() 127 | ``` 128 | 129 | ### Search for articles that have a relation with a launch 130 | **v3** 131 | ```python 132 | import requests 133 | 134 | response = requests.get( 135 | "https://api.spaceflightnewsapi.net/v3/articles/launch/41699701-2ef4-4b0c-ac9d-6757820cde87").json() 136 | print(response) 137 | ``` 138 | 139 | **v4** 140 | ```python 141 | import requests 142 | 143 | response = requests.get( 144 | "https://api.spaceflightnewsapi.net/v4/articles?launch=41699701-2ef4-4b0c-ac9d-6757820cde87").json() 145 | print(response["results"]) 146 | ``` 147 | 148 | You can now also search for articles that relate to multiple launches: 149 | ```python 150 | import requests 151 | 152 | response = requests.get( 153 | "https://api.spaceflightnewsapi.net/v4/articles?launch=41699701-2ef4-4b0c-ac9d-6757820cde87,d8bd2b25-129b-4ab7-95d9-fb8ad1fdd73e").json() 154 | print(response["results"]) 155 | ``` 156 | 157 | If you want to get only articles that have a related launch or event, you can use the `has_launch` and `has_event` parameters: 158 | ```python 159 | import requests 160 | 161 | response = requests.get( 162 | "https://api.spaceflightnewsapi.net/v4/articles?has_launch=true").json() 163 | print(response["results"]) 164 | ``` 165 | 166 | Above options also work for events. 167 | -------------------------------------------------------------------------------- /faqs/faq_SNAPI.md: -------------------------------------------------------------------------------- 1 | ![SNAPI Cover](../assets/snapi_poster.png) 2 | 3 | [![Website](https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/b475617700544896da25f3dbf70857c111d93299/assets/badge_snapi_website.svg)](https://spaceflightnewsapi.net/) 4 | [![Documentation](https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/b475617700544896da25f3dbf70857c111d93299/assets/badge_snapi_doc.svg)](https://api.spaceflightnewsapi.net/v4/docs) 5 | [![Discord](https://img.shields.io/badge/Discord-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/p7ntkNA) 6 | 7 | # Spaceflight News API - Frequently Asked Questions (FAQ) 8 | 9 | ## Table of Contents 10 | 11 | 12 | 13 | * [About](#about) 14 | * [What is the *Spaceflight News API* (SNAPI)?](#what-is-the-spaceflight-news-api-snapi) 15 | * [Is SNAPI still under development?](#is-snapi-still-under-development) 16 | * [Free and paid access](#free-and-paid-access) 17 | * [Is SNAPI free to use?](#is-snapi-free-to-use) 18 | * [Do I need an API key?](#do-i-need-an-api-key) 19 | * [Data](#data) 20 | * [What data is available?](#what-data-is-available) 21 | * [Where does SNAPI get its data from?](#where-does-snapi-get-its-data-from) 22 | * [How often is the data updated?](#how-often-is-the-data-updated) 23 | * [What date/time format is used in SNAPI?](#what-datetime-format-is-used-in-snapi) 24 | * [Which types of news sources are allowed in SNAPI?](#which-types-of-news-sources-are-allowed-in-snapi) 25 | * [How is the data linked to other APIs?](#how-is-the-data-linked-to-other-apis) 26 | * [API](#api) 27 | * [How to filter the API response?](#how-to-filter-the-api-response) 28 | * [How to apply multiple filters?](#how-to-apply-multiple-filters) 29 | * [How to get more results in a single request?](#how-to-get-more-results-in-a-single-request) 30 | * [How to paginate through the data?](#how-to-paginate-through-the-data) 31 | * [How to sort the API response?](#how-to-sort-the-api-response) 32 | * [Help & Contact](#help--contact) 33 | * [Where do I get help?](#where-do-i-get-help) 34 | * [How do I report a bug/data mistake?](#how-do-i-report-a-bugdata-mistake) 35 | * [How do I contact the SNAPI staff?](#how-do-i-contact-the-snapi-staff) 36 | 37 | ## About 38 | 39 | > ### What is the *Spaceflight News API* (SNAPI)? 40 | 41 | The Spaceflight News API is a REST API providing space news data including : 42 | 43 | - Space-related news articles from numerous websites 44 | - Space-related blog posts from numerous websites 45 | - Daily summary reports from the International Space Station 46 | 47 | > ### Is SNAPI still under development? 48 | 49 | SNAPI is still maintained and improved regularly. However, most of the upgrades are related to the news sources or 50 | backend improvements, requiring no version bump. New features or data can also be added without bumping the API 51 | version if they are fully compatible. 52 | 53 | When a new version is released, the announcement will be made the on the 54 | TSD [Discord server](https://discord.gg/p7ntkNA) and Twitter ([TSD](https://twitter.com/TheSpaceDevs) 55 | , [SNAPI](https://twitter.com/the_snapi)) first. 56 | 57 | ## Free and paid access 58 | 59 | > ### Is SNAPI free to use? 60 | 61 | Yes, SNAPI is fully free to use for everyone. However, if you are using SNAPI in a commercial project, we would 62 | appreciate if you consider supporting the project through [Patreon](https://www.patreon.com/thespacedevs) or a 63 | one-time [donation](https://ko-fi.com/derkweijers). 64 | 65 | > ### Do I need an API key? 66 | 67 | No API key is required to use SNAPI. 68 | 69 | ## Data 70 | 71 | > ### What data is available? 72 | 73 | A list of the main data elements available through SNAPI is available on its [website](https://spaceflightnewsapi.net/). 74 | The full list of endpoints is available in the [documentation](https://api.spaceflightnewsapi.net/v4/docs). 75 | 76 | > ### Where does SNAPI get its data from? 77 | 78 | When available, the data is imported from RSS feeds or the API of source websites. 79 | Otherwise, it is acquired through automatic web scraping. 80 | Some basic filters are applied during processing to remove irrelevant data. 81 | 82 | 83 | > ### How often is the data updated? 84 | 85 | The importer runs every 10 minutes to check for new data, so new articles can take up to 10 minutes to appear in the 86 | API. 87 | 88 | > ### What date/time format is used in SNAPI? 89 | 90 | All the datetime fields in SNAPI follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, for example 91 | `2022-10-16T07:21:04.448ZZ`. All times are UTC, as indicated by the `Z` at the end of the datetime string. 92 | 93 | > ### Which types of news sources are allowed in SNAPI? 94 | 95 | All professional space-related news sources are allowed in SNAPI for the `articles` endpoint. 96 | For the `blogs` endpoint, high-quality amateur content is also allowed. 97 | 98 | It is possible to suggest new sources to be added to SNAPI by posting in the 99 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 100 | [Discord server](https://discord.gg/p7ntkNA). 101 | 102 | > ### How is the data linked to other APIs? 103 | 104 | Articles are linked to [Launch Library 2](https://thespacedevs.com/llapi) launches and events through their LL2 ID. 105 | 106 | ## API 107 | 108 | > ### How to filter the API response? 109 | 110 | Filters can be applied to an API query by adding `?=` to the end of the query. 111 | 112 | For example: https://api.spaceflightnewsapi.net/v4/articles?title_contains=NASA 113 | 114 | > ### How to apply multiple filters? 115 | 116 | Multiple filters can be applied by separating them with `&`. 117 | 118 | For example: https://api.spaceflightnewsapi.net/v4/articles/?title_contains=NASA&published_at_lte=2022-01-01 119 | 120 | 121 | > ### How to get more results in a single request? 122 | 123 | It is possible to increase the number of results per request by using the `limit=` filter. 124 | 125 | > ### How to paginate through the data? 126 | 127 | The API supports pagination through the `offset=` filter. This filter is automatically applied to the request 128 | URL and provided in the `next` field of the response. 129 | 130 | > ### How to sort the API response? 131 | 132 | The API response can be sorted by any of the available fields using `ordering=`. Use `-` to sort in 133 | descending order. 134 | 135 | ## Help & Contact 136 | 137 | > ### Where do I get help? 138 | If you need any help with SNAPI, you can ask in the 139 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 140 | [Discord server](https://discord.gg/p7ntkNA) or email [derk@spaceflightnewsapi.net](mailto:derk@spaceflightnewsapi.net). 141 | 142 | > ### How do I report a bug/data mistake? 143 | 144 | If you found a bug or data mistake, let the staff know in the 145 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 146 | [Discord server](https://discord.gg/p7ntkNA), or 147 | email [derk@spaceflightnewsapi.net](mailto:derk@spaceflightnewsapi.net). 148 | 149 | > ### How do I contact the SNAPI staff? 150 | 151 | There are two main ways to contact the SNAPI staff: 152 | 153 | - On the [Discord server](https://discord.gg/p7ntkNA). 154 | - By email to [derk@spaceflightnewsapi.net](mailto:derk@spaceflightnewsapi.net). -------------------------------------------------------------------------------- /assets/badge_snapi_website.svg: -------------------------------------------------------------------------------- 1 | WEBSITEWEBSITE -------------------------------------------------------------------------------- /assets/badge_snapi_doc.svg: -------------------------------------------------------------------------------- 1 | DOCUMENTATIONDOCUMENTATION -------------------------------------------------------------------------------- /assets/badge_tsd_website.svg: -------------------------------------------------------------------------------- 1 | WEBSITEWEBSITE -------------------------------------------------------------------------------- /faqs/faq_TSD.md: -------------------------------------------------------------------------------- 1 | ![TSD Cover](../assets/tsd_cover.png) 2 | 3 | [![Website](https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/e36b2c250ce7fcd4a801c1ed6cb1f9f9d031696b/assets/badge_tsd_website.svg)](https://thespacedevs.com/) 4 | [![Discord](https://img.shields.io/badge/Discord-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/p7ntkNA) 5 | [![Twitter](https://img.shields.io/badge/Twitter-%231DA1F2.svg?style=for-the-badge&logo=Twitter&logoColor=white)](https://twitter.com/TheSpaceDevs) 6 | [![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/TheSpaceDevs) 7 | 8 | # The Space Devs - Frequently Asked Questions (FAQ) 9 | 10 | ## Table of Contents 11 | 12 | 13 | 14 | * [Terms of use](#terms-of-use) 15 | * [About](#about) 16 | * [What is *The Space Devs* (TSD) ?](#what-is-the-space-devs-tsd) 17 | * [How is TSD managed?](#how-is-tsd-managed) 18 | * [How is TSD funded?](#how-is-tsd-funded) 19 | * [APIs](#apis) 20 | * [Which APIs are available?](#which-apis-are-available) 21 | * [Are the APIs free to use?](#are-the-tsd-apis-free-to-use) 22 | * [Partners](#partners) 23 | * [What is a TSD partner?](#what-is-a-tsd-partner) 24 | * [How do I become a TSD partner?](#how-do-i-become-a-tsd-partner) 25 | * [Users](#users) 26 | * [What is a *verified* TSD user?](#what-is-a-verified-tsd-user) 27 | * [How do I become a *verified* TSD user?](#how-do-i-become-a-verified-tsd-user) 28 | * [Staff](#staff) 29 | * [What does the TSD staff do?](#what-does-the-tsd-staff-do) 30 | * [How do I become a TSD staff member?](#how-do-i-become-a-tsd-staff-member) 31 | * [Contact](#contact) 32 | * [How do I contact the TSD staff?](#how-do-i-contact-the-tsd-staff) 33 | 34 | 35 | 36 | ## Terms of use 37 | 38 | > By using any service provided by The Space Devs, you agree to the following terms. These apply, but are not limited, to the data provided through the Launch Library 2 API and the Spaceflight News API. 39 | 40 | You are free to use the data in any way, shape, or form, and share what you create with it. Please refrain from forwarding it without adding value. 41 | Due to the large amount of manual labor involved, we cannot however guarantee a 100% accuracy of all the information provided. 42 | 43 | Attribution is not mandatory, but is encouraged and appreciated. It helps us avoid circular data sourcing and makes it easier to reach us in case changes are required. 44 | 45 | ## About 46 | 47 | > ### What is *The Space Devs* (TSD)? 48 | 49 | *The Space Devs* (TSD) is a [nonprofit](https://en.wikipedia.org/wiki/Nonprofit_organization_laws_by_jurisdiction#France) managed by a group of space enthusiast developers and librarians working on APIs to improve public knowledge and accessibility of spaceflight information. 50 | It was created in 2020 by core staff members of Space Launch Now, the Spaceflight News API and the original Launch Library API with the following objectives: 51 | 52 | - Maintain and promote the Launch Library 2 and Spaceflight News APIs. 53 | - Integrate with third-party APIs and services ([TSD partners](#partners)). 54 | - Unite its users into a community of space enthusiast developers ([TSD users](#users)). 55 | 56 | *The Space Devs* is **not** affiliated with any space agencies or spaceflight companies. 57 | 58 | > ### How is TSD managed? 59 | 60 | [Registered in France](https://www.journal-officiel.gouv.fr/pages/associations-detail-annonce/?q.id=id:202400010198), it is managed fully online by a core staff team of developers and librarians involved in the project foundation in 2020 and its predecessors as staff members of the original Launch Library and Space Launch Now APIs. 61 | 62 | A crucial management goal is to ensure that the APIs are and remain **financially sustainable in the long-term**, while remaining **free to use**. 63 | This is what the original Launch Library API failed to achieve and the reason this goal is of utmost importance for Launch Library 2, and *The Space Devs* in general. It comes with implications on access rates explained in more details [here](#are-the-tsd-apis-free-to-use). 64 | 65 | > ### How is TSD funded? 66 | 67 | As a nonprofit, *The Space Devs* is **not** a company aiming to make profit. 68 | Its only purpose is to provide up-to-date data through APIs accessible for free while also covering its expenses. 69 | 70 | 100% of its funding comes from the community through [Patreon](https://www.patreon.com/TheSpaceDevs) subscriptions and [Paypal](https://www.paypal.com/donate/?hosted_button_id=UCPX4EL6E9JFA) donations. 71 | The Patreon subscriptions are also a way to access the Launch Library 2 API at higher rates than at the free tier. 72 | More details [here](#are-the-tsd-apis-free-to-use). 73 | 74 | ## APIs 75 | 76 | > ### Which APIs are available? 77 | 78 | *The Space Devs* currently handles and provides two APIs first-hand: 79 | 80 | - [Launch Library 2 (LL2)](https://thespacedevs.com/llapi) : Launch Library 2 is a REST API for rocket launch data. As 81 | the official successor of the original Launch Library API, which it replaced in 2020, it keeps its core features 82 | whilst also including everything the broader Space Launch Now API had to offer. The result is a large database 83 | delivering a more complete experience for each rocket launch and space event. Since 2021, all orbital rocket launches 84 | since Sputnik-1 in 1957 are included in the database. 85 | 86 | A complete list of features and documentation links are available on the TSD 87 | website [here](https://thespacedevs.com/llapi). A dedicated FAQ is available [here](faq_LL2.md). 88 | 89 | 90 | - [Spaceflight News API (SNAPI)](https://thespacedevs.com/snapi) : The Spaceflight News API is a REST API that provides 91 | space news articles, which are automatically detected. These are then manually linked to relevant Launch 92 | Library 2 `launch` and `event` objects, allowing for *related-news* sections on launch and event pages or *view 93 | launch* and *view event* links on news articles. 94 | 95 | A complete list of features and documentation links are available on the TSD 96 | website [here](https://thespacedevs.com/snapi). A dedicated FAQ is available [here](faq_SNAPI.md). 97 | 98 | Two other APIs are provided by TSD partners : 99 | 100 | - [Launch Dashboard API (LDAPI)](https://github.com/shahar603/Launch-Dashboard-API) : The Launch Dashboard API is an 101 | Open Source 102 | REST API of rocket launch telemetry. All the data is acquired through optical character recognition (OCR) of launch 103 | webcasts. The data is then processed by a physics simulator, filtered to remove anomalies and annotated before 104 | becoming available to API requests. 105 | 106 | More information about the API and can be found on the GitHub 107 | repository [here](https://github.com/shahar603/Launch-Dashboard-API). 108 | 109 | 110 | - [Flight Club API](https://flightclub.io) : The Flight Club API is a REST API providing access to flight club data and 111 | calculators. 112 | 113 | You can find more information about Flight Club [here](https://flightclub.io) and the API 114 | documentation [here](https://api.flightclub.io/swagger-ui.html). 115 | 116 | > ### Are the TSD APIs free to use? 117 | 118 | Both Launch Library 2 and the Spaceflight News API are **free to use**. 119 | 120 | ***However***, server costs still need to be covered by TSD. For this purpose and to avoid abuse, access to **Launch 121 | Library 2**, our most popular and therefore most expensive API, is limited to **15 calls per hour**. During development, 122 | a development API is available with no rate limiting but stale data (more info [here](faq_LL2.md#what-is-lldev)). If you 123 | want higher rates, to refresh data more often close to launches or to support a larger project, it is possible to 124 | increase this limit by using an API key (see how to acquire one [here](faq_LL2.md#how-do-i-get-an-api-key) and how to 125 | use 126 | it [here](faq_LL2.md#how-do-i-use-my-api-key)). 127 | 128 | Whether you need higher rates than the free tier or not, we **heavily** encourage you to cache the output on your side 129 | and avoid having user clients query TSD APIs directly. 130 | 131 | ## Partners 132 | 133 | > ### What is a TSD partner? 134 | 135 | There are three *founding partners* of *The Space Devs* : [Space Launch Now](https://spacelaunchnow.me), 136 | [Go4Liftoff](https://go4liftoff.com), and the [Spaceflight News API](https://spaceflightnewsapi.net). The first two 137 | were the main actors of the foundation of The Space Devs when it was created to carry over the Launch Library torch. 138 | The third and final one, which was then already a close partner of the two others, became part of The Space Devs at its 139 | foundation by making SNAPI a TSD API. 140 | 141 | Other TSD partners satisfy one or more of the following requirements: 142 | 143 | - Provide an API or service that integrates LL2 and/or SNAPI IDs into their own data to allow for easy cross-linking. 144 | - Provide a custom service to TSD built according to TSD-defined needs. 145 | 146 | Current TSD partners are listed on the TSD website [here](https://thespacedevs.com/networkpartners). 147 | 148 | > ### How do I become a TSD partner? 149 | 150 | To qualify as a potential TSD partner, you need to meet at least one of the requirements listed above. 151 | 152 | If you think you do, please contact our staff to discuss a potential partnership. 153 | 154 | ## Users 155 | 156 | > ### What is a *verified* TSD user? 157 | 158 | *Verified* TSD users are services, projects or entities that actively use data provided by TSD APIs. They are 159 | listed on the users page of the TSD website [here](https://thespacedevs.com/networkusers). 160 | 161 | > ### How do I become a *verified* TSD user? 162 | 163 | To be considered a *verified* TSD user and added to the users page of the TSD website 164 | [here](https://thespacedevs.com/networkusers), send a message with the required format in 165 | the [`#users`](https://discord.com/channels/676725644444565514/805510731780587540) channel (see the 166 | [pinned message](https://discord.com/channels/676725644444565514/805510731780587540/805518057052569601)) of the 167 | TSD [Discord server](https://discord.gg/p7ntkNA), or contact our staff directly. 168 | 169 | ## Staff 170 | 171 | > ### What does the TSD staff do? 172 | 173 | There are two main roles in the TSD team: developers maintain and improve the infrastructure of TSD APIs and services, 174 | while librarians maintain the data. 175 | 176 | The core staff members of *The Space Devs* are developers and librarians part of the project since its foundation 177 | in 2020. They were all previously staff members of Space Launch Now or the original Launch Library API. 178 | 179 | Other staff members are new librarians who have joined the project since 2020 to help with the ever-increasing workload 180 | associated with the data. 181 | 182 | > ### How do I become a TSD staff member? 183 | 184 | The TSD team usually sends proposals to people deemed to be a helpful addition to the team when a need for additional 185 | staff is felt. If you think you can fit a role and would like to join the TSD team, please contact our staff. 186 | 187 | Note that the TSD team is not always looking for new staff members. So your application might not be considered for a 188 | long time. 189 | 190 | ## Contact 191 | 192 | > ### How do I contact the TSD staff? 193 | 194 | There are two main ways to contact the TSD staff: 195 | 196 | - On the [Discord server](https://discord.gg/p7ntkNA). 197 | - By email to [support@thespacedevs.com](mailto:support@thespacedevs.com). 198 | 199 | Additionally, you can also find us on [Twitter](https://twitter.com/TheSpaceDevs), 200 | [Facebook](https://www.facebook.com/TheSpaceDevs/) and [LinkedIn](https://www.linkedin.com/company/42873958/). 201 | 202 | 203 | -------------------------------------------------------------------------------- /announcements/LL_230_changelog.md: -------------------------------------------------------------------------------- 1 | ![LL2 Cover](../assets/ll2_230.png) 2 | 3 | [![Documentation](../assets/badge_ll2_doc.svg)](https://ll.thespacedevs.com/2.3.0/swagger/) 4 | [![Discord server](https://img.shields.io/badge/Discord-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/p7ntkNA) 5 | [![Patreon](https://img.shields.io/badge/Patreon-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/TheSpaceDevs) 6 | 7 | # Launch Library 2.3.0 Release 8 | 9 | ## Table of Contents 10 | 11 | 12 | 13 | * [Context](#-context) 14 | * [Highlights](#-highlights) 15 | * [Frequently Asked Questions (FAQs)](#-frequently-asked-questions-faqs) 16 | * [Full changelog](#-full-changelog) 17 | 18 | ## 📢 Context 19 | 20 | > Here is some history and context for this release. If you don't care (which is perfectly OK), feel free to [skip this 21 | > section entirely](#-highlights) 😄 Happy reading! ~[Arnaud](https://github.com/Nosudrum) 22 | 23 | ### 📜 How we got here 24 | 25 | The initial release of Launch Library 2.0.0 was made public in july 2020. Since then, two other versions have been 26 | released to implement small changes that required breaking changes in the API schema. 27 | 28 | - 2.1.0 was released in november 2020 with some field type changes, a few new filters, new config endpoints, and a 29 | new launch status (TBC); 30 | - 2.2.0 was released in february 2021, with docs fixes, throttle bypasses, and some new & removed fields. 31 | 32 | Since february 2021, many new features have been added to version 2.2.0, as they did not break the API schema: mission 33 | patches, webcast automation, automated stats, comma-separated filters, spacecraft landings, T-0 precision, spacewalks, 34 | launch timelines, and many more smaller improvements. 35 | 36 | This means that since 2021, all ideas requiring breaking changes to the API schema (i.e. a version bump) piled up 37 | while we worked on improving 2.2.0. In late 2022, we started keeping track with GitHub issues of every single change we 38 | wanted to see in the next LL2 version. By early 2024, we had completed all the development work for 2.2.0 features. 39 | 40 | ### 💻 Version 2.3.0 development work 41 | 42 | Before diving head first into all the piled up issues, we held two dev team meetings to go over every issue and plan how 43 | we would tackle the breaking database and API changes while ensuring full backwards compatibility with previous API 44 | versions. 45 | 46 | That being done, we started working on version 2.3.0 on february 11. Some 100+ issues and 200+ pull 47 | requests later, Launch Library version 2.3.0 is ready. 48 | 49 | User-facing changes aside, this release is a **major** step-up in code maintainability. All endpoints have 50 | undergone major refactoring work, and so have the tests which now cover all fields of all 2.3.0 endpoints. A lot of 51 | work also went into improving the human documentation, making the schema 100% accurate for client generation, and 52 | optimizing database queries for performance. 53 | 54 | **TL;DR - we really worked hard on this.** 55 | 56 | ### 🙏 Acknowledgements 57 | 58 | Special thanks go to [Lucas](https://github.com/lucas-stauder), who contributed significantly to this effort, as 59 | well as [Jacques](https://github.com/JRascagneres) and [Caleb](https://github.com/ItsCalebJones), who were essential in 60 | tackling the more intricate and infrastructure-related tasks. 61 | 62 | And of course, a big shoutout as well to [our Patrons](https://thespacedevs.com/supportus) who make this project 63 | **possible** and **sustainable**. 🤍 64 | 65 | ## ✨ Highlights 66 | 67 | - 🤖 **Launch designator automation** 68 | - Moved from the `mission` object to the `launch` object, the `launch_designator` field is now fully automated for 69 | all previous launches. 70 | - This 71 | allows [querying LL2 launches using COSPAR IDs](https://ll.thespacedevs.com/2.3.0/launches/?launch_designator=1957-001,2021-123), 72 | and effortlessly expanding LL2 data with other sources (e.g. 73 | live object status & orbital elements from [Celestrak](https://celestrak.org/satcat/records.php?INTDES=2024-047)) 74 | - 📸 **Rework of images as reusable objects** 75 | - The `image_url`, `profile_url`, `logo_url`, etc. fields have been reworked to link to a new `Image` object that 76 | can be reused to allow for better caching and crediting. 77 | - This object has crediting & license information, as well as a ready to use thumbnail and, when relevant, multiple 78 | related `ImageVariant` objects (e.g. various versions of a logo) 79 | - 🚀 **New launch status** 80 | - The `Payload Deployed` (ID 9) launch status has been added as an intermediate status before confirmation of 81 | payload AOS. 82 | - It is returned as `In Flight` (ID 6) in 2.2.0 and older versions. 83 | - 🪐 **Celestial bodies** 84 | - A new `CelestialBody` object has been created for `Orbit`, `Location`, and `LandingLocation` objects, as well as 85 | filtering options on relevant endpoints. 86 | - ⚠️ **This means 2.3.0 can now include launches from other bodies than Earth.** These are hidden in 2.2.0 and 87 | previous versions. 88 | - 🏳️ **Countries** 89 | - All the country & nationality information has been reworked to use one or multiple linked `Country` objects. 90 | - This new object includes all the information needed to collect relevant metadata (e.g. flags) from other sources, 91 | or to accurately display one or multiple nationalities. 92 | - 🛰️ **Payloads** 93 | - *While the idea remains not to transform LL2 into an exhaustive SATCAT*, new `Payload`, `PayloadFlight` objects 94 | allow the addition of uncrewed & non-reusable space objects to rockets in a similar fashion as the 95 | existing `Spacecraft` objects. 96 | - This makes it possible to provide a broader coverage (e.g. with dockings, landings, etc.) for high-profile 97 | missions. 98 | - For exhaustive (but perhaps less detailed) payload information, the `launch_designator` automation allows easy 99 | expansion with data from other sources. 100 | - ⚙️ **Multiple spacecraft per rocket & dockings rework** 101 | - `Rocket` objects can now have *multiple* `SpacecraftFlight` (& `PayloadFlight`) objects, to support some edge 102 | cases (e.g. Apollo CSM & LEM) 103 | - Dockings have been reworked to be possible between any two `SpacecraftFlight`, `PayloadFlight`, and `SpaceStation` 104 | objects, to support all space dockings. 105 | - ⚡ **Performance** 106 | - Significant effort has been made to optimize serializers and database queries for performance. 107 | - This should™️ mean the end of server timeouts when querying large amounts of data at once, despite the increased 108 | complexity of 2.3.0 responses. 109 | 110 | ## ❓ Frequently Asked Questions (FAQs) 111 | 112 | Ok maybe not *frequently*, but these are questions we expect so here are immediate answers. 113 | 114 | > ### Why is a new version needed? 115 | 116 | A new API version is needed to implement breaking changes in the schema (e.g. field type changes or removals). 117 | Feature and data structure rework ideas requiring breaking changes have piled up over multiple years, so they could all 118 | be bundled into a massive new API version. This is LL 2.3.0. 119 | 120 | > ### Will older version keep working? 121 | 122 | Yes. All older versions remain functional as full backwards compatibility has been implemented. 123 | 124 | > ### Do I need to migrate? 125 | 126 | Not necessarily, but it is recommended. 127 | 128 | > ### Will older versions remain supported? 129 | 130 | Bugs reported in older versions will be fixed as long as they do not impact the latest version. 131 | Questions related to older versions will continue to be answered to the best of our abilities. 132 | 133 | > ### Will older versions get any new features? 134 | 135 | No. 136 | 137 | ## 🧵 Full changelog 138 | 139 | > ### Acronyms 140 | > - `FK` means `Foreign Key`, which creates a single relation from one object to another (reusable) one. For example, 141 | the `Location` FK in the `Pad` model. One pad can only be linked to one location, but one location is often linked 142 | to multiple pads. 143 | > - `M2M` means `Many-To-Many`, which creates relations from one object to multiple other ones. For example, 144 | the `AstronautFlight` M2M in the `Spacewalk` model, for linking multiple crew members to a single spacewalk object. 145 | 146 | ### 🆕 New models 147 | 148 | - added the `CelestialBody` model (+ `CelestialBodyType` config), used as FK in the `Location`, `LandingLocation`, 149 | and `Orbit` models 150 | - added the `Country` config to replace string-based information in the `Agency`, `Astronaut`, `Location`, and `Pad` 151 | models 152 | - added the `Image` and `ImageVariant` models (+ `ImageLicense` and `ImageVariantType` configs), used as FK in place of 153 | almost all previous `image_url`, `profile_url`, `logo_url`, etc. fields across many models 154 | - added the `LauncherConfigurationFamily` model, used as M2M in the `LauncherConfiguration` model 155 | - added the `Payload` and `PayloadFlight` models (+ `PayloadType` config) 156 | - added the `ProgramType` config, used as FK in the `Program` model 157 | - added the `SocialMediaLink` model (+ `SocialMedia` config), used as M2M in the `Astronaut` and `Agency` models 158 | - added the `SpacecraftConfigurationFamily` model, used as M2M in the `SpacecraftConfiguration` model 159 | - added the `SpacecraftConfigurationType` config, used as FK in the `SpacecraftConfiguration` model 160 | 161 | ### 🆕 New fields on existing models 162 | 163 | - added the `active` and `image` fields to `Location` and `Pad` models 164 | - added the `duration` and `turn_around_time` duration fields to the `SpacecraftFlight` model 165 | - added the `fastest_turnaround` duration fields to the `Pad`, `Launcher`, `LauncherConfiguration`, `Spacecraft`, 166 | and `SpacecraftConfiguration` models 167 | - added the `geo_capacity` and `sso_capacity` fields to the `LauncherConfiguration` model 168 | - added the `is_placeholder` field to the `Launcher` model 169 | - added the `is_placeholder` field to the `LauncherConfig` model (for cases where the exact variant is not 170 | known yet, e.g. a generic Vulcan Centaur or Ariane 6) 171 | - added the `live` boolean field to the `VidURL` model, and automated it 172 | - added payload and spacecraft landing statistics to the `Agency` model 173 | - added stats to the `SpacecraftConfiguration` model 174 | - added the `astronauts` field to the `Event` model 175 | - added the `attempted_landings` and `failed_landings` fields to the `LandingLocation` model 176 | 177 | ### 🔀 Field/filter renaming & reorganization 178 | 179 | - combined the functionality of comma-separated `lsp__ids` and the single `lsp__id` filters into `lsp__id` on the `launches` endpoint 180 | - moved the `launch_designator` field (unpopulated before 2.3.0) from the `Mission` model to the `Launch` model, and 181 | automated it 182 | - renamed the `docked` field in the `SpaceStation` model to `currently_docked` 183 | - renamed the `infoURLs` and `vidURLs` fields in the `Launch` model to `info_urls` and `vid_urls` 184 | - renamed the `location` field in the `Landing` model to `landing_location` 185 | - renamed the `manufacturer` filter on the `SpacecraftConfiguration` endpoint to `agency`, to match the filtering field 186 | - renamed the `nation_url` field in the `Agency` model to `social_icon` 187 | 188 | ### ⚙️ Type & format changes 189 | 190 | - made the `apogee`, `gto_capacity` `launch_mass`, `leo_capacity`, and `to_thrust` fields floats in the 191 | `LauncherConfiguration` model 192 | - made the `family` field in the `LauncherConfiguration` model a FK to the new `LauncherConfigurationFamily` config 193 | - made the `founding_year` field an integer in the `Agency` model 194 | - made the `latitude` and `longitude` fields floats in the `Location` and `Pad` models 195 | - made the `launch_cost` field an integer in the `LauncherConfiguration` model 196 | - made the `spacecraft_stage` field in the `Rocket` model an M2M relation to the `SpacecraftFlight` model 197 | - made the `status`, `net`, `window_start` and `window_end` fields non-nullable in the `Launch` model 198 | - made the `status` field in the `Launcher` model a `LauncherStatus` FK, and added filtering by FK ID on the endpoint 199 | - made the `type` field in the `Agency` model a FK to the `AgencyType` config 200 | - replaced the `agency_id` field in the `Pad` model with an M2M relation to the `Agency` model 201 | - replaced the `turn_around_time_days` integer field in the `FirstStage` model by an 202 | ISO8601-formatted `turn_around_time` 203 | duration field 204 | - reworked the `DockingEvent` model to make it work with a chaser and a target, both of which can be 205 | a `Spacecraft`, `SpaceStation`, or `Payload` FK 206 | - reworked the `DockingLocation` model to make it have both a `Spacecraft` FK and a `Payload` FK 207 | 208 | ### 🗑️ Field removals 209 | 210 | - removed the `holdreason` field from the `Launch` model 211 | - removed the `launch_library_url` fields from all models where it was still present (remains from the LL1 era) 212 | - removed the `news_url` and `video_url` fields from the `Event` model (replaced by `InfoURL` and `VidURL` 213 | M2Ms like for launches, as introduced in 2.2.0) 214 | - removed the `r_spacex_api_id` field from the `Launch` model and the associated filter on the endpoint (API deprecated) 215 | - removed the `the nation_url` field from the `SpacecraftConfiguration` model 216 | - removed the `twitter` and `instagram` fields from the `Astronaut` model 217 | - removed the `vehicle_range` field from the `LauncherConfiguration` model 218 | 219 | ### 🚀 Misc 220 | 221 | - added the `Payload Deployed` (ID 9) launch status, returned as `In Flight` (ID 6) in older versions 222 | - added `webcast_live` automation for NASA+ URLs in `VidURL` objects 223 | 224 | ### 📈 API & endpoint enhancements 225 | 226 | - added admin panel validations to prevent common human errors (e.g. multiple librarians editing something at the same 227 | time) 228 | - automated the endpoint docs to provide fully exhaustive filtering, sorting, ordering, and generic information 229 | - major refactor of all serializers to clean up code and allow full tests coverage, this means some fields might have 230 | been added/removed to/from the `list` and `normal` modes 231 | - major refactor of all endpoints to ensure polymorphism is properly documented in the schema 232 | - removed the non-strict LSP & location filtering option from the `Launch` endpoint that prevented proper filter 233 | documentation 234 | - renamed all endpoint URLs to use plural and `snake_case` 235 | - significant database-related performance improvements on all endpoints 236 | -------------------------------------------------------------------------------- /faqs/faq_LL2.md: -------------------------------------------------------------------------------- 1 | ![LL2 Cover](../assets/ll2_historic_launches.png) 2 | 3 | [![Documentation](https://raw.githubusercontent.com/TheSpaceDevs/Tutorials/a10b94f4476ce7a134f9b6e0e75ef761cb35a446/assets/badge_ll2_doc.svg)](https://ll.thespacedevs.com/docs/) 4 | [![Discord server](https://img.shields.io/badge/Discord-%237289DA.svg?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/p7ntkNA) 5 | 6 | # Launch Library 2 - Frequently Asked Questions (FAQ) 7 | 8 | ## Table of Contents 9 | 10 | 11 | 12 | * [About](#about) 13 | * [What is *Launch Library 2* (LL2)?](#what-is-launch-library-2-ll2) 14 | * [How is LL2 related to the original Launch Library API?](#how-is-ll2-related-to-the-original-launch-library-api) 15 | * [Is LL2 still under development?](#is-ll2-still-under-development) 16 | * [Will there be a Launch Library 3?](#will-there-be-a-launch-library-3) 17 | * [Free and paid access](#free-and-paid-access) 18 | * [Is LL2 free to use?](#is-ll2-free-to-use) 19 | * [What is lldev?](#what-is-lldev) 20 | * [Do I need an API key?](#do-i-need-an-api-key) 21 | * [How do I get an API key?](#how-do-i-get-an-api-key) 22 | * [How do I use my API key?](#how-do-i-use-my-api-key) 23 | * [How do I change my API key?](#how-do-i-change-my-api-key) 24 | * [How do I check how many API calls I have left?](#how-do-i-check-how-many-api-calls-i-have-left) 25 | * [Data](#data) 26 | * [What data is available?](#what-data-is-available) 27 | * [Where does LL2 get its data from?](#where-does-ll2-get-its-data-from) 28 | * [How often is the data updated?](#how-often-is-the-data-updated) 29 | * [How are webcasts (`vid_urls`) selected and sorted?](#how-are-webcasts-vid_urls-selected-and-sorted) 30 | * [How to exclude TSD videos from the webcast list?](#how-to-exclude-tsd-videos-from-the-webcast-list) 31 | * [What is a Launch Service Provider (LSP)?](#what-is-a-launch-service-provider-lsp) 32 | * [What date/time format is used in LL2?](#what-datetime-format-is-used-in-ll2) 33 | * [What country code format is used in LL2?](#what-country-code-format-is-used-in-ll2) 34 | * [What are the different launch statuses used in LL2?](#what-are-the-different-launch-statuses-used-in-ll2) 35 | * [Which suborbital launches are allowed in LL2?](#which-suborbital-launches-are-allowed-in-ll2) 36 | * [Why do launches remain `In Flight` after deployment?](#why-do-launches-remain-in-flight-after-deployment) 37 | * [How is the data linked to other APIs?](#how-is-the-data-linked-to-other-apis) 38 | * [API](#api) 39 | * [How to filter the API response?](#how-to-filter-the-api-response) 40 | * [How to apply multiple filters?](#how-to-apply-multiple-filters) 41 | * [How to apply filters with multiple values?](#how-to-apply-filters-with-multiple-values) 42 | * [How to get more results in a single request?](#how-to-get-more-results-in-a-single-request) 43 | * [How to paginate through the data?](#how-to-paginate-through-the-data) 44 | * [How to access all the data and related objects?](#how-to-access-all-the-data-and-related-objects) 45 | * [How to sort the API response?](#how-to-sort-the-api-response) 46 | * [Why do past items appear in the `upcoming` endpoints?](#why-do-past-items-appear-in-the-upcoming-endpoints) 47 | * [Help & Contact](#help--contact) 48 | * [Is LL2 down?](#is-ll2-down) 49 | * [Where do I get help?](#where-do-i-get-help) 50 | * [How do I report a bug/data mistake?](#how-do-i-report-a-bugdata-mistake) 51 | * [How do I contact the LL2 staff?](#how-do-i-contact-the-ll2-staff) 52 | 53 | ## About 54 | 55 | > ### What is *Launch Library 2* (LL2)? 56 | 57 | Launch Library 2 is a REST API providing space launch data including but not limited to : 58 | 59 | - All orbital and some suborbital launches, with related data such as webcasts, launch service providers, etc. 60 | - Spaceflight events 61 | - Space stations with related data such as dockings, expeditions 62 | - Astronauts and their flights 63 | - Launch vehicles, reusable first stages and spacecraft 64 | - Programs : Apollo, Tiangong, Starship, etc. and their related data 65 | 66 | > ### How is LL2 related to the original Launch Library API? 67 | 68 | The retirement of the original Launch Library API was decided in December 2019 after the person paying for 69 | its expensive servers decided to leave the project. The remaining active librarians of the original Launch Library API 70 | teamed up with the staff of the Space Launch Now API to merge both efforts into an official successor : 71 | [Launch Library 2](https://thespacedevs.com/llapi). This new API would be managed by a new entity, separate of the 72 | user projects, called [The Space Devs](https://thespacedevs.com). 73 | 74 | The creation of The Space Devs was officially announced with the release of LL2 in July 2020, while the original Launch 75 | Library API stopped being updated in autumn 2020 and was discontinued in early 2021. 76 | 77 | > ### Is LL2 still under development? 78 | 79 | LL2 is still maintained and improved regularly. However, most of the upgrades are related to the admin panel or 80 | performance improvements, requiring no version bump. New features or data can also be added without bumping the LL2 81 | version if they are fully compatible. 82 | 83 | When a new version is released, the announcement will be made on the TSD [Discord server](https://discord.gg/p7ntkNA) 84 | and [Twitter](https://twitter.com/TheSpaceDevs) first. 85 | 86 | > ### Will there be a Launch Library 3? 87 | 88 | There is no plan for a major version update of the Launch Library API at the moment. However, it is still under 89 | development and updated regularly. If there ever is, news will be announced on the 90 | TSD [Discord server](https://discord.gg/p7ntkNA) 91 | and [Twitter](https://twitter.com/TheSpaceDevs) first. 92 | 93 | ## Free and paid access 94 | 95 | > ### Is LL2 free to use? 96 | 97 | All the data in Launch Library 2 is free to access with up to 15 API calls per hour (per IP). 98 | An API key is needed for higher access rates (per key). 99 | 100 | > ### What is lldev? 101 | 102 | The `lldev` prefix (instead of `ll`) in LL2 calls can be used to reach the development API. It is the same API , but 103 | with no rate limits and a limited, stale data set. This should be used during development and testing, but 104 | never in production. 105 | 106 | > ### Do I need an API key? 107 | 108 | The 15 calls per hour limit should be enough for most uses. If you feel like you need more (for a mobile app for 109 | example), then consider setting up a cache updated within the 15 calls per hour limit that serves data to your clients 110 | instead. 111 | 112 | Additionally, it is recommended if real-time data is needed, to perform fewer API calls per hour overall and more 113 | around the time of the launch. Such optimizations of the API calls distribution can reduce the need for a paid API key. 114 | 115 | If these measures are not enough, then an API key is needed to get higher access rates. 116 | 117 | > ### How do I get an API key? 118 | 119 | To get an API key, first choose the tier that satisfies your needs on 120 | our [Patreon](https://www.patreon.com/TheSpaceDevs). 121 | Then head over to our [website](https://thespacedevs.com/supportus) and login with your Patreon account to generate your 122 | key. 123 | 124 | > ### How do I use my API key? 125 | 126 | To use your API key, add the following header in your request : 127 | 128 | - key: `"Authorization"` 129 | - value: `"Token "`, where `` is your API key (without the `<>`). 130 | 131 | You can check that your API key is working by performing a request to the 132 | [`/api-throttle`](https://ll.thespacedevs.com/2.3.0/api-throttle/) endpoint and checking the `ident` field in the 133 | response: if it displays your IP, then your API key is not properly set up in your request. 134 | 135 | Note that queries to this endpoint do not count towards your API calls limit. 136 | 137 | 138 | > ### How do I change my API key? 139 | 140 | To change your API key, head over to our [website](https://thespacedevs.com/supportus), login with your Patreon account, 141 | and follow the instructions. 142 | 143 | > ### How do I check how many API calls I have left? 144 | 145 | To check your API calls usage and rate limits, perform a request to the 146 | [`/api-throttle`](https://ll.thespacedevs.com/2.3.0/api-throttle/) endpoint. This will return your current rate limit, 147 | the frequency of that limit (e.g. 3600 for 1 hour), the number of calls you have made within that period, and the time 148 | in seconds until you can make calls again if you are being rate-limited. 149 | 150 | Note that queries to this endpoint do not count towards your API calls limit. 151 | 152 | 153 | ## Data 154 | 155 | > ### What data is available? 156 | 157 | A list of the main data elements available through LL2 is available on its [web page](https://thespacedevs.com/llapi). 158 | The full list of endpoints is available in the [documentation](https://ll.thespacedevs.com/docs/). 159 | 160 | > ### Where does LL2 get its data from? 161 | 162 | The day-to-day data in LL2 is added and maintained using public sources of three different types : 1st-party, 2nd-party 163 | and community. 164 | The 1st party data comes directly from space agencies, launch service providers, satellite operators, etc. and is 165 | usually considered the most reliable. The 2nd party data comes from space journalists and news outlets which have proven 166 | reliable over the years. The community data comes from the forums or user reports and is not necessarily reliable. 167 | 168 | The historic data in LL2 is sourced from Jonathan McDowell's [GCAT](https://planet4589.org/space/gcat/), 169 | [Gunter's Space Page](https://space.skyrocket.de/index.html), [spacefacts.de](http://www.spacefacts.de/), as well 170 | as other public databases. 171 | 172 | > ### How often is the data updated? 173 | 174 | The data in LL2 is updated as often as needed, which means multiple times within an hour during launches or events, 175 | and usually a few times per day as new information is available. 176 | 177 | > ### How are webcasts (`vid_urls`) selected and sorted? 178 | 179 | When available, only official webcasts are provided in LL2. If there are multiple options, the english-speaking hosted 180 | webcasts with the highest quality are prioritized. 181 | 182 | The priority value is an increasing number from the main webcasts to the secondary ones. This is done to easily sort 183 | the available webcasts from the most important to the least. 184 | 185 | > ### How to exclude TSD videos from the webcast list? 186 | 187 | After launches, some `vid_urls` with the lowest priority value are launch summary videos provided through the TSD YouTube 188 | channel. These are simple edits to cut out the countdown sequence and holds. 189 | 190 | To exclude this, it is possible to use the YouTube API to filter out the videos from the 191 | [TSD YouTube channel](https://www.youtube.com/channel/UCCKiR4D6hbgk9lW9UwxZXxg). 192 | 193 | > ### What is a Launch Service Provider (LSP)? 194 | 195 | A Launch Service Provider (LSP) is a space agency or company that operates a launch (in the economics sense). 196 | It is not always the operator of the rocket, but is the entity responsible for the launch as seen from customers. 197 | 198 | > ### What date/time format is used in LL2? 199 | 200 | All the datetime fields in LL2 follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, for example 201 | `2022-08-18T09:17:04Z`. All times are UTC, as indicated by the `Z` at the end of the datetime string. 202 | 203 | > ### What country code format is used in LL2? 204 | 205 | LL2 country codes use **comma-separated** [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) codes. 206 | 207 | > ### What are the different launch statuses used in LL2? 208 | 209 | The list of launch statuses, along with their ID, description, etc. is available on the [launchstatus config endpoint](https://ll.thespacedevs.com/2.3.0/config/launch_statuses/). 210 | 211 | > ### Which suborbital launches are allowed in LL2? 212 | 213 | All orbital launch attempts are included in LL2, however the suborbital launches considered must be livestreamed and 214 | meet at least one of the following criteria: 215 | 216 | - Target an apogee of at least 100 km 217 | - Carry crew higher than 80 km 218 | - Draw significant public interest 219 | 220 | It is possible to suggest suborbital launches to be added to LL2 by asking librarians in the 221 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 222 | [Discord server](https://discord.gg/p7ntkNA). 223 | 224 | To remove suborbital launches from LL2 queries, it is possible to use the `include_suborbital=false` filter. 225 | 226 | > ### Why do launches remain `In Flight` after deployment? 227 | 228 | Launches where a liftoff was confirmed remain `In Flight` until a confirmation of acquisition of signal of the main 229 | payload is received. If not available (rideshare with many payloads, classified payloads, etc.), the launch is 230 | considered 231 | successful when the launch service provider counts it as such, usually after deployment. 232 | 233 | > ### How is the data linked to other APIs? 234 | 235 | LL2 launch and event IDs are used in the following APIs: 236 | 237 | - [Spaceflight News API](https://spaceflightnewsapi.net/): to link related news articles 238 | - [Flight Club](https://flightclub.io/): to link launch trajectory and telemetry data 239 | - [Launch Dashboard API](https://github.com/shahar603/Launch-Dashboard-API): to link launch telemetry data 240 | - [SpaceX API](https://github.com/r-spacex/SpaceX-API): to link SpaceX-specific launch data 241 | 242 | ## API 243 | 244 | > ### How to filter the API response? 245 | 246 | Filters can be applied to an API query by adding `?=` to the end of the query. 247 | 248 | For example: https://ll.thespacedevs.com/2.3.0/launches/upcoming/?lsp__name=SpaceX 249 | 250 | > ### How to apply multiple filters? 251 | 252 | Multiple filters can be applied by separating them with `&`. 253 | 254 | For example: https://ll.thespacedevs.com/2.3.0/launches/upcoming/?lsp__name=SpaceX&is_crewed=true 255 | 256 | > ### How to apply filters with multiple values? 257 | 258 | Only a handful of filters can be applied with multiple values, such as `spacecraft_config__ids`, `location__ids`, 259 | `lsp__id`. For these, multiple values can be applied by separating them with `,`. 260 | 261 | > ### How to get more results in a single request? 262 | 263 | It is possible to increase the number of results per request **up to 100** by using the `limit=` filter. 264 | 265 | While it can help minimize the number of overall API calls, keep in mind that increasing the number of results per 266 | request will result in longer API response times. 267 | 268 | > ### How to paginate through the data? 269 | 270 | The API supports pagination through the `offset=` filter. This filter is automatically applied to the request 271 | URL and provided in the `next` field of the response. 272 | 273 | Therefore, regardless of the number of results per request, easy pagination can be done by performing API requests with 274 | the URL in the `next` field until it is empty. 275 | 276 | > ### How to access all the data and related objects? 277 | 278 | To access all the data and related objects (webcast URLs on the launch endpoint for example), use the 279 | `mode=detailed` filter. 280 | 281 | > ### How to sort the API response? 282 | 283 | The API response can be sorted by any of the available fields using `ordering=`. To switch from ascending to 284 | descending order, add `-` to the beginning of the field name: `ordering=-`. 285 | 286 | > ### Why do past items appear in the `upcoming` endpoints? 287 | Launches and events remain in the `upcoming` endpoint for 24 hours to allow services to update them with their final 288 | information (launch outcome, mainly) without needing an additional call to the `previous` endpoint. 289 | 290 | This behavior can be disabled using the `hide_recent_previous=true` filter. 291 | 292 | ## Help & Contact 293 | 294 | > ### Is LL2 down? 295 | 296 | The status of LL2 can be checked [here](https://ll.thespacedevs.com/health_check/). If you notice any issue, please 297 | let the staff know in the 298 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 299 | [Discord server](https://discord.gg/p7ntkNA). 300 | 301 | > ### Where do I get help? 302 | If you need any help with LL2, you can ask in the 303 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 304 | [Discord server](https://discord.gg/p7ntkNA) or email [support@thespacedevs.com](mailto:support@thespacedevs.com). 305 | 306 | > ### How do I report a bug/data mistake? 307 | 308 | If you found a bug or data mistake, let the staff know in the 309 | [`💬feedback-and-help`](https://discord.com/channels/676725644444565514/1019976345884827750) forum of the TSD 310 | [Discord server](https://discord.gg/p7ntkNA), or email [support@thespacedevs.com](mailto:support@thespacedevs.com). 311 | 312 | > ### How do I contact the LL2 staff? 313 | 314 | There are two main ways to contact the LL2 staff: 315 | 316 | - On the [Discord server](https://discord.gg/p7ntkNA). 317 | - By email to [support@thespacedevs.com](mailto:support@thespacedevs.com). 318 | --------------------------------------------------------------------------------