Elite Galaxy Online. API Documentation v Elite Galaxy Online. All rights reserved

Transcription

1 Elite Galaxy Online API Documentation v2.1

2 Contents 1. Version Control Overview of Elite Galaxy Online API Retrieving Data from Elite Galaxy Online Retrieving Star System Data Overview Query Variables Return Values Example Usage Retrieving Object Data Overview Query Variables Return Values Example Usage Retrieving Galactic Record Data records/get_latest_records records/get_object_types records/get_ring_types records/get_record_categories records/get_record_names Retrieving List Data Submitting Data to Elite Galaxy Online... 22

3 1. Version Control Version Date Changes /09/2015 Initial Release /09/2015 Updated ego_system/get_details to also include object_id Added ego_system/get_details_full /09/2015 Added ego_system/get_system_list /11/2015 Added new submission entry to allow uploading images directly to the multi scanner Added new multiscan class to allow retrieval of information from the multiscanner /11/2015 Added support for third party use of the Elite Galaxy Online discovery scanner as an OCR engine for system view screenshots Added ability to retrieve the results of a scan submitted via the API /04/2017 Complete rewrite of the API to simplify and tie in with the new Ship Log Reader /5/2017 Increased object return limit on objects/get_data to 10,000

4 2. Overview of Elite Galaxy Online API The Elite Galaxy Online API is made up of two components: API endpoints which allow for retrieving data from the site using a GET http request. API endpoints which allow data to be submitted to the site using a POST http request. Retrieving Data Using the API to retrieve data from the site involves making a GET request to a specific URL. For example, to retrieve data for the Sol system you can use the following URL: Or alternatively, if you wish to retrieve data for Jupiter, you can use: Due to the public nature of this data, no API key is required to use these endpoints. All URL s which form part of the retrieval API are structured as follows: Each of the endpoints will generate an output in standard JSON format. Section 3 of this document describes the different endpoints which are currently available. Submitting Data Objects can be recorded at Elite Galaxy Online by submitting a POST request containing the Scan event from the Player Journal log file which is now created by Elite Dangerous. This scan event along with a few other variables such as the System Name will then be parsed at Elite Galaxy Online and recorded. This part of the api requires a user login and api key to be submitted as part of the POST request. See section 4 for more details.

5 3. Retrieving Data from Elite Galaxy Online 3.1. Retrieving Star System Data Overview The systems class can be used to retrieve information about any star systems which have been recorded at Elite Galaxy Online. It contains one method called get_data which accepts a number of query variables to allow only systems which match a certain set of criteria to be returned. URI: Note that for performance reasons, I have currently limited this api call to only return data for a maximum of 10,000 systems. This can be increased but I want to avoid any potential impact at this stage to the main site. Please contact me if this limit is preventing you from using the api in the way you might need to.

6 Query Variables The table below shows all of the optional query variables which can be used with the /systems/get_data/ api endpoint. All string type query variables can accept the asterix character * to use as a wildcard. For example, using /systems/get_data/?system_name=wredg* will return data for all systems that begin with wredg. Alternatively, multiple wildcard characters can be used for example, /systems/get_data/?system_name=*sector* will return data for all systems which contain sector in their name. Query Variable Type Description system_name string Applies a filter on system name first_recorded_by string Applies a filter on the first recorded by field this is the display name of the user who first recorded an object within this system

7 Return Values Return Value Definition status Indicates whether the call to the API is OK or has encountered an error query_parameters An array of the SQL WHERE statements which have been generated and applied based on the url query variables number_of_systems_returned A count of the total number of systems which have been returned. Indicates if the max api return limit has been reached system_data system_link url linking to the system at Elite Galaxy Online system_name The name of the system system_description The description of the system as entered by the commander who first recorded an object within it at Elite Galaxy Online first_recorded_by The display name of the user who first recorded an object in this system orrery_status Indicates whether an orrery is currently available for this system galactic_coordinates Array containing the galactic coordinates of this system if recorded

8 Example Usage Return data for all systems containing sol in their system name Return data for all systems first recorded by commander wolzan wolzan

9 3.2. Retrieving Object Data Overview The objects class can be used to retrieve information about any objects which have been recorded at Elite Galaxy Online. It contains one method called get_data which accepts a number of query variables to allow only objects which match a certain set of criteria to be returned. URI: Note that for performance reasons, I have currently limited this api call to only return data for a maximum of 10,000 objects. This can be increased but I want to avoid any potential impact at this stage to the main site. Please contact me if this limit is preventing you from using the api in the way you might need to.

10 Query Variables The table below shows all of the optional query variables which can be used with the /objects/get_data/ api endpoint. All string type query variables can accept the asterix character * to use as a wildcard. For example, using /objects/get_data/?system_name=wredg* will return data for all objects which exist in systems that begin with wredg. Alternatively, multiple wildcard characters can be used for example, /objects/get_data/?system_name=*sector* will return data for all objects which exist in systems which contain sector in their name. Query Variable Type Description object_name string Applies a filter on object name system_name string Applies a filter on system name object_group string Applies a filter on object group i.e. Stars, Gas Giants / Water Giants or Terrestrial Planets object_type string Applies a filter on object type i.e. Class B Star first_discovered_by string Applies a filter on the first discovered by field note this is the name of the commander who first discovered the object in Elite Dangerous and not who first recorded it at Elite Galaxy Online. recorded_by string Applies a filter on the recorded by field this is the display name of the user who recorded the object at Elite Galaxy Online date_recorded_from datetime Applies a filter on the date recorded field to only show objects recorded from this date onwards. date_recorded_to datetime Applies a filter on the date recorded field to only show objects recorded up to an including this date min_surface_temp number Applies a filter on the surface temp field to only show objects with a surface temperature above or equal to the min_surface_temp max_surface_temp number Applies a filter on the surface temp field to only show objects with a surface temperature below or equal to the max_surface_temp min_earth_mass number Applies a filter on the earth mass field to only show objects with an earth mass above or equal to the min_earth_mass - Note earth mass is only relevant for Gas Giants and Terrestrial Planets as Stars use the solar mass measurement max_earth_mass number Applies a filter on the earth mass field to only show objects with an earth mass below or equal to the max_earth_mass - Note earth mass is only relevant for Gas Giants and Terrestrial Planets as Stars use the solar mass measurement min_radius number Applies a filter on the radius field to only show objects with a radius above or equal to the min_radius - Note radius is only relevant for Gas Giants and Terrestrial Planets as Stars use the solar radius measurement max_radius number Applies a filter on the radius field to only show objects with a radius below or equal to the max_radius - Note radius is only relevant for Gas Giants and Terrestrial Planets as Stars use the solar radius measurement

11 Query Variable Type Description min_mean_density number Applies a filter on the mean density field to only show objects with a mean density above or equal to the min_mean_density max_mean_density number Applies a filter on the mean density field to only show objects with a mean density below or equal to the max_mean_density min_surface_gravity number Applies a filter on the surface gravity field to only show objects with a surface gravity above or equal to the min_ surface gravity Note surface gravity is not present for Stars max_surface_gravity number Applies a filter on the surface gravity field to only show objects with a surface gravity below or equal to the max_ surface gravity Note surface gravity is not present for Stars min_age number Applies a filter on the age field to only show objects with an age above or equal to the min_age Note age only exists for Stars max_age number Applies a filter on the age field to only show objects with an age below or equal to the max_age Note age only exists for Stars min_solar_mass number Applies a filter on the solar mass field to only show objects with a solar mass above or equal to the min_solar_mass Note solar mass only exists for Stars max_ solar_mass number Applies a filter on the solar mass field to only show objects with a solar mass below or equal to the max_solar_mass Note solar mass only exists for Stars min_solar_radius number Applies a filter on the solar radius field to only show objects with a solar radius above or equal to the min_solar_ radius Note solar radius only exists for Stars max_ solar_radius number Applies a filter on the solar radius field to only show objects with a solar radius below or equal to the max_solar_ radius Note solar radius only exists for Stars min_abs_magnitude number Applies a filter on the absolute magnitude field to only show objects with an absolute magnitude above or equal to the min_abs_magnitude Note absolute magnitude only exists for Stars max_ abs_magnitude number Applies a filter on the absolute magnitude field to only show objects with an absolute magnitude below or equal to the max_abs_magnitude Note absolute magnitude only exists for Stars min_orbital_period number Applies a filter on the orbital period field to only show objects with an orbital period above or equal to the min_orbital_period max_orbital_period number Applies a filter on the orbital period field to only show objects with an orbital period below or equal to the max_orbital_period min_semi_major_axis number Applies a filter on the semi major axis field (measured in AU) to only show objects with a semi major axis above or equal to the min_semi_major_axis max_semi_major_axis number Applies a filter on the semi major axis field (measured in AU) to only show objects with a semi major axis below or equal to the max_semi_major_axis min_semi_major_axis_km number Applies a filter on the semi major axis km field (measured in km) to only show objects with a semi major axis km above or equal to the min_semi_major_axis_km max_semi_major_axis_km number Applies a filter on the semi major axis km field (measured in km) to only show objects with a semi major axis below or equal to the max_semi_major_axis_km min_orbital_eccentricity number Applies a filter on the orbital eccentricity field to only show objects with an orbital eccentricity above or equal to the min_orbital_

12 Query Variable Type Description eccentricity max_orbital_ eccentricity number Applies a filter on the orbital eccentricity field to only show objects with an orbital eccentricity below or equal to the max_orbital_ eccentricity min_orbital_inclination number Applies a filter on the orbital inclination field to only show objects with an orbital inclination above or equal to the min_orbital_ inclination max_orbital_ inclination number Applies a filter on the orbital inclination field to only show objects with an orbital inclination below or equal to the max_orbital_ inclination min_arg_of_periapsis number Applies a filter on the argument of periapsis field to only show objects with an argument of periapsis above or equal to the min_arg_of_periapsis max_ arg_of_periapsis number Applies a filter on the argument of periapsis field to only show objects with an argument of periapsis below or equal to the max_arg_of_periapsis min_rotational_period number Applies a filter on the rotational period field to only show objects with a rotational period above or equal to the min_rotational_period max_rotational_period number Applies a filter on the rotational period field to only show objects with a rotational period below or equal to the max_rotational_period min_axial_tilt number Applies a filter on the axial tilt field to only show objects with an axial tilt above or equal to the min_axial_tilt max_axial_tilt number Applies a filter on the axial tilt field to only show objects with an axial tilt below or equal to the max_axial_tilt

13 Return Values Return Value Definition status Indicates whether the call to the API is OK or has encountered an error query_parameters An array of the SQL WHERE statements which have been generated and applied based on the url query variables number_of_objects_returned A count of the total number of objects which have been returned. Indicates if the max api return limit has been reached object_data object_link url linking to the object at Elite Galaxy Online object_name The name of the object system_name The name of the system in which the object is located object_description The description of the object as entered by the commander who recorded it at Elite Galaxy Online object_group The group classification of the object i.e. Star, Gas Giant or Terrestrial Planet object_type The object type classification of the object first_discovered_by The name of the commander who first discovered the object in game (if known) recorded_by The display_name of the commander who recorded the object at Elite Galaxy Online date_recorded The data the object was recorded at Elite Galaxy Online. main_data An array of the main recorded data for an object. Note that the fields in this array vary depending on whether the object is classified as a Star, Gas Giant or Terrestrial Planet. orbit_data An array of the orbital data which has been recorded for an object. Note that stars which are the system centre of mass will not have orbital data solid_composition_data An array of the solid compositional information for an object. Note this will only be available for terrestrial planet type objects and will return null for stars and gas giants. atmosphere_composition_data An array of the atmospheric compositional information for an object. Note that this will only be available for terrestrial planets with atmospheres and gas giants. ring_data An array of the ring information which has been recorded for an object if applicable.

14 Example Usage Return data for all objects within the Liaedin system Return data for all objects in systems where the system name begins with wred Return data for all objects in systems where the system name contains sector Return data for all high metal content planets which have been recorded by Commander Wolzan metal content planet&recorded_by=commander wolzan Return data for all Terrestrial Planets with a surface temperature ranging from 200K to 240K inclusive and a surface gravity equal to 1.5g or above Planet&min_surface_temp=200&max_surface_temp=240&min_surface_gravity=1.5

15 3.3. Retrieving Galactic Record Data The records class can be used to retrieve information about the current galactic records held at Elite Galaxy Online The records class contains the following API endpoints: Method Query Variables Description get_latest_records object_type, ring_type, category, Returns information for every galactic record currently held at Elite Galaxy Online record_name get_object_types None Returns the list of object types as used in the galactic records get_ring_types None Returns the list of ring types as used in the galactic records get_record_categories None Returns the list of record categories as used in the galactic records get_record_names None Returns the list of record names as used in the galactic records

16 records/get_latest_records URI: Description: Returns information for every galactic record currently held at Elite Galaxy Online Query Variables: object type (optional), ring_type (optional), category (optional), record_name (optional) The Query Variables can be used to filter down the records as required Return Values: Return Value Definition status Indicates whether the call to the API is OK or has encountered an error records object_type The object type classification which the record is associated with ring_type The ring type if any which the record is associated with category The record category record_name The name of the record current_value The currently held value including the units current_value_no_units The currently held value excluding the units current_number_of_objects The current number of objects holding the record Example Usage: M Star Returns:

17 records/get_object_types URI: Description: Returns the list of object types as used in the galactic records Query Variables: None Return Values: Return Value status object_types Definition Indicates whether the call to the API is OK or has encountered an error The list of object types which can be used as filters in the get_latest_records endpoint

18 records/get_ring_types URI: Description: Returns the list of ring types as used in the galactic records Query Variables: None Return Values: Return Value status ring_types Definition Indicates whether the call to the API is OK or has encountered an error The list of ring types which can be used as filters in the get_latest_records endpoint

19 records/get_record_categories URI: Description: Returns the list of record categories as used in the galactic records Query Variables: None Return Values: Return Value status record_categories Definition Indicates whether the call to the API is OK or has encountered an error The list of record categories which can be used as filters in the get_latest_records endpoint

20 records/get_record_names URI: Description: Returns the list of record names as used in the galactic records Query Variables: None Return Values: Return Value status record_names Definition Indicates whether the call to the API is OK or has encountered an error The list of record names which can be used as filters in the get_latest_records endpoint

21 3.4. Retrieving List Data The lists class can be used to retrieve information about the various lists such as volcanism types and atmosphere types which are used at Elite Galaxy Online The lists class contains the following API endpoints: Method Query Variables Description object_groups None Returns the list of object groups star_types None Returns the list of star classifications gas_giant_types None Returns the list of gas giant classifications terrestrial_planet_types None Returns the list of terrestrial planet classifications atmospheric_elements None Returns the list of atmospheric elements solid_elements None Returns the list of solid composition elements terraform_status_types None Returns the list of terraform status types atmosphere_types None Returns the list of atmosphere types volcanism_types None Returns the list of volcanism types ring_types None Returns the list of ring types ring_reserves_types None Returns the list of ring reserves types Example Usage: Returns:

22 4. Submitting Data to Elite Galaxy Online New objects can be recorded at Elite Galaxy Online via the API by submitting a Scan event from the player journal logs which are now created by Elite Dangerous. The Scan event will then be parsed and recorded at the site and the api will return the outcome including whether the object broke a galactic record. To submit a scan event in this way, you must submit a POST request to the following URL. The body of your post request should contain a JSON object of field value pairs containing the information being submitted An example of a typical post request is shown below: There are 9 inputs required for this submission as described below: Input ID Input Name Description input_1 user_login Should contain a valid Elite Galaxy Online user login input_2 user_api_key Should contain a valid Elite Galaxy Online user api key for the user specified in input_1 input_3 application_id A unique id number to identify the application which is submitting the object input_4 application_auth_code A unique authorisation code for the application as defined in input_3 input_5 Scan event The full Scan event line taken from the player journal file with the

23 double quotation characters escaped Input_6 system_name The name of the system in which the scan was performed Input_7 X coordinate of the system The x coordinate of the system Input_8 Y coordinate of the system The y coordinate of the system Input_9 Z coordinate of the system The z coordinate of the system Notes on these input fields Input_1 and input_2 contain the users Elite Galaxy Online user login and user api key. This is required so the discovery can be recorded against the correct account. These should be unique to each user of your application. Input_3 and input_4 contain the application_id and application_auth_code. I have added these to the api for 3 reasons as follows: I want to be able to track usage of which discoveries are coming from which external applications When an object is recorded via an external application, the object is tagged with a source which then shows up across the site as shown in the example below where an object has been recorded using the Elite Galaxy Online Comms Link application. This looks pretty cool and the image can be linked to your external application. If you are interested in making your external application submit discoveries to Elite Galaxy Online using this api then please get in touch with me at commander.wolzan@elitegalaxyonline.com and i ll generate an application_id and authorisation code for you. These should then be stored in your application in a way that is not visible to your users.

24 Return Values on Successful Submission Once a successful POST request is made to this api, you will receive back a confirmation as shown below: [ response ][ is_valid ] indicates whether the submission passed the initial data checks or not. If a field failed validation then [ response ][ validation_messages ] will contain details of any failures as shown below: On successful submission, the response object will contain [ response ][ confirmation_message ]. This contains the outcome of the api submission and contains the following fields. field Is_valid message object_id unique_record_holder object_link system_link description Indicates whether the object was successfully recorded or whether it failed for some reason i.e. object already exists. 1 = valid, 0 = not valid Message describing the outcome of the submission The internal object_id at Elite Galaxy Online associated with the submission Indicates whether the new discovery is a unique record holder i.e. broke a a galactic record url link to the Elite Galaxy Online page to view the object url link to the Elite Galaxy Online page to view the system containing the object