LIneA Occultation Predictions Database API

Introduction

The LIneA Occultation Prediction Database (LOPD) API is a solution for querying and managing predictions of stellar occultations programatically. With this API, you can:

  • Search for occultation prediction events by various parameters such as date, time, star magnitude.
  • Customize and filter occultation prediction events based on date/time intervals, star magnitude limits, object names, dynamical classes, and subclasses.
  • Access geolocation filtering (experimental) for refined results, among other things.
  • Query asteroids properties, and more.

The LOPD API is intended for researchers and enthusiasts looking to integrate or explore occultation prediction events quickly and easily. The API uses the JSON format for requests and responses, adhering to RESTful standards for architecture and design.

In addition to providing the schema in the OpenAPI standard, this API also offers Swagger UI and ReDoc interfaces. These interfaces are tools that allow for interactive and user-friendly visualization and testing of the API.

Swagger UI is a tool that provides an interactive and user-friendly interface, enabling the execution of requests and viewing of API responses.

ReDoc is a tool that offers an elegant and responsive interface, allowing navigation through the API documentation.

You can access the interfaces via the URL /docs/, selecting the desired option in the top right corner of the page.

Warning

The current version of the LOPD API is 1.0.0. The API is in the development phase and may undergo changes without prior notice. To stay updated on API updates and news, visit the repository of the API.

Terms of Use

To use the LOPD API, you must agree to the following terms of use:

  • Use the API responsibly and ethically.
  • Limit the number of API requests to 1000 per day and 100 per hour. If you require a higher limit, contact API support.
  • Aknowledge the API as the source of the data used or displayed in your application, including a link to the API documentation.
  • Notify API support of any issues, errors, or failures encountered while using the API.
  • Accept that the API provides no guarantee of availability, quality, accuracy, or security of the data, and you are solely responsible for the use and consequences of the API in your application.

By using the LOPD API, you declare that you have read, understood, and agreed to the above terms of use. Non-compliance with the terms of use may result in the suspension or cancellation of your access to the API.

Resources

The LOPD API handles the following features:

  • Occultation: It is an event that contains information regarding the occulting object, such as date and time, star apparent magnitude, object geocentric distance, etc. Additionally, it provides information about the candidate star to be occulted, such as right ascension, declination, apparent magnitude, etc. Moreover, it includes predictive information about the event, such as the expected drop in magnitude during the occultation, among other data.
  • Asteroid: Aggregates the set of information about a small body in the Solar System, including its orbital properties and, when available, some physical properties.
  • Base Dynclass: Contains the main dynamic classifications of asteroids as defined by Skybot.
  • Dynclass: Contains the set of dynamic subclassifications of asteroids as defined by Skybot.

Endpoints

The LOPD API features the following endpoints, organized by categories:

Occultations

  • GET /api/occultations: Returns a list of occultation predictions, which can be filtered by object, date, among other parameters.
  • GET /api/occultations/{id}: Returns the details of a specific occultation prediction identified by its ID.
  • GET /api/occultations/{id}/get_or_create_map: Returns the details of the map for a specific occultation prediction, generating the map if it doesn't exist.
  • GET /api/occultations/asteroids_with_prediction: Returns the list of asteroids with predictions in the database.
  • GET /api/occultations/dynclass_with_prediction: Returns the list of dynamic subclasses (Skybot) of asteroids with predictions in the database.
  • GET /api/occultations/base_dynclass_with_prediction: Returns the list of base dynamic classes (Skybot) of asteroids with predictions in the database.

Asteroids

  • GET /api/asteroids: Returns the list of asteroids registered in the database.
  • GET /api/asteroids/{id}: Returns the details of an asteroid identified by its ID.
  • GET /api/asteroids/count: Returns the number of asteroids registered in the database.
  • GET /api/asteroids/dynclasses: Returns the list of dynamic subclasses (Skybot) of asteroids registered in the database.
  • GET /api/asteroids/base_dynclasses: Returns the list of base dynamic classes (Skybot) of asteroids registered in the database.
  • GET /api/asteroids/with_prediction: Returns the list of asteroids registered in the database with occultation prediction and their details.

Errors

The LOPD API can return the following errors, specifying the error codes and messages:

  • 400 Bad Request: The request was malformed or invalid, for example, missing a required parameter or using an incorrect format.
  • 401 Unauthorized: The request was not authenticated, for example, missing or using an invalid API key.
  • 403 Forbidden: The request was authenticated, but does not have permission to access the requested resource, for example, trying to edit or remove a book that does not belong to your personal collection.
  • 404 Not Found: The requested resource was not found, for example, using a nonexistent ID or an invalid route.
  • 405 Method Not Allowed: The HTTP method used in the request is not supported by the requested resource, for example, using the POST method on an endpoint that only accepts the GET method.
  • 429 Too Many Requests: The request exceeded the limit of requests allowed by the API, for example, making more than 1000 requests per day or more than 100 requests per hour.
  • 500 Internal Server Error: The request caused an internal error on the API server, for example, due to a bug or application failure.