Skip to main content

Favorites & Groups

Base path: /v1/favorites

Auth required: Yes

What this service does

  • Save satellites you care about and organize them into groups
  • Add/remove/move favorites; list all, by group, or check statuses in bulk

Concepts

  • Every favorite lives in a group; a default group is created for you
  • Adding/removing is idempotent — repeating a request won’t error
  • You can create custom groups with names, colors, and descriptions

Add favorites​

  • POST /v1/favorites/add
  • Body:
{ "norad_ids": ["25544","70000"], "group_id": 10 }
  • 200 Response:
{
  "message": "Favorites updated successfully",
  "added_favorites": ["25544"],
  "already_favorites": ["70000"],
  "total_added": 1
}
  • Errors: 500

Remove favorites​

  • POST /v1/favorites/remove
  • Body:
{ "norad_ids": ["25544"], "group_id": 10 }
  • 200 Response:
{
  "message": "Favorites removed successfully",
  "removed_favorites": ["25544"],
  "not_found_favorites": [],
  "total_removed": 1
}

List favorites (all or by group)​

  • GET /v1/favorites/list?group_id=10
  • 200 Response (grouped):
{
  "groups": [
    {
      "group_id": 10,
      "group_name": "Default",
      "group_color": "#3B82F6",
      "is_default": true,
      "favorites": [{"norad_id":"25544","satellite_name_official":"ISS (ZARYA)","added_at":"2025-02-05T01:00:00Z"}],
      "favorite_count": 1
    }
  ],
  "total_count": 1,
  "total_groups": 1
}

Check favorites status​

  • GET /v1/favorites/check?norad_ids=25544,70000
  • 200 Response:
[
  {"norad_ids": ["25544"], "is_favorite": true},
  {"norad_ids": ["70000"], "is_favorite": false}
]
  • Errors: 400 (invalid query format)

Move favorites​

  • POST /v1/favorites/move/
  • Body:
{ "norad_ids": ["25544"], "target_group_id": 11 }
  • 200 Response:
{
  "message": "Favorites moved successfully",
  "moved_favorites": ["25544"],
  "not_found_favorites": [],
  "target_group_name": "Important",
  "total_moved": 1
}

Groups​

  • Create: POST /v1/favorites/groups/
{ "name":"Important", "description":"High-priority sats", "color":"#FF5733" }
  • Get all: GET /v1/favorites/groups/
  • Update: PUT /v1/favorites/groups/{group_id}
  • Delete: DELETE /v1/favorites/groups/{group_id}
  • Get favorites in group: GET /v1/favorites/groups/{group_id}/favorites/

Errors:

  • 400: name conflict, default group modifications
  • 404: group not found
  • 500: unexpected