Support for automated data queries

The "API support" from the NEOCC web services is currently limited to some HTTP GET requests with raw text-based responses. Note that it is considered as experimental — pending funding availability we hope to be able to offer a more convenient interface at some point. However, this means that we may modify, change or remove the interface at any moment and without advance warning. In that case, a best effort will be made to update this help page with the new details.

Usage

As mentioned above, all automated data accesses use the HTTP protocol and the GET method, that is, the request and all parameters are transmitted in the URL. All URLs below should be prefixed with our server URL: http://neo.ssa.esa.int/
Some have parameters, which are represented with the format $param, and explained in a table below.

Parameters reference

Placeholder name Basic data type Explanation Limits / validity
$desig String Designator of an object, written as the name or provisional designation (without spaces). If the object is numbered, the catalog number may precede the string, separated by a space. Examples (without quotes): "2007VK184", "433 Eros". Any in the database for which the relevant data is available.
$orbptype String Used when querying for orbital parameters. It is formed by two values in sequence: first is the type of the parameters, which may be equinoctial or keplerian. Then, a number selects the definition epoch of the orbit: 0 for the middle of the observational arc of the object (which changes only when there are new observations), or 1 for a date close to the present (which changes regularly). One of the following: eq0, eq1, ke0, ke1.
$obscode String Observatory code, location of the observer in the generation of ephemerides. One of the MPC-recognized codes, or 500 for the geocenter.
$tini
$tend
UTC date/time Initial and final times for ephemerides generation, in the format YYYY-mm-ddTHH:MMZ. Given the maximum precision of the ephemerides generated by the portal (minutes), no leap second effects are considered. Examples (without quotes): "1981-03-25T17:25Z", "2033-08-31T11:37Z". Final time must by after the initial time. Also, undisclosed limitations are placed both on the distance of either date to the present and on the separation between the dates.
$dt Real number Time step for ephemerides generation. Must be positive. Also, undisclosed limitations are placed on the total number of ephemerides lines generated.
$dtunit String Unit for $dt. One of the following: days, hours, minutes.

Note that the possible space in designators like "433 Eros" (or anywhere else) has to be URL-encoded, either as "+" or as "%20". Most browsers will do so automatically if the address is written with a space, but some tools or libraries might not e.g. wget might work but curl could fail in the same system. Please make sure to check this first if the response by the server is "400 Bad request".

List of API endpoints

Direct download of list files

These URLs can be invoked directly without any extra parameters. They are equivalent to clicking the Download as TXT button in the relevant pages.

Risk list (normal)

URL: PSDB-portlet/download?file=esa_risk_list

Output format: a line with the last update date/time, followed by a table of fields delimited by pipe characters (U+007C). The first three lines are headers, with the second field under "diameter" recording an asterisk if the value has been estimated from the absolute magnitude.

Last Update: 2019-10-03 07:34 UTC Object | Diameter | VI Max | VIs | Num/des. Name | m | *=Y | Date/Time | IP max | PS max |TS | Vel km/s | Years | IP cum | PS cum | AAAAAAAAA AAAAAAAAAAAAAAAA | NNNN | A | YYYY-MM-DD HH:MM | EEEEEEEE | NNN.NN | NN | NNN.NN | YYYY-YYYY | EEEEEEEE | NNN.NN | 2010RF12 | 9 | * | 2095-09-05 23:50 | 6.00E-2 | -3.26 | 0 | 12.29 | 2095-2117 | 6.05E-2 | -3.26 | 99942 Apophis | 375 | | 2068-04-12 15:13 | 1.88E-6 | -3.67 | 0 | 12.62 | 2068-2116 | 2.30E-6 | -3.59 | 443104 2013XK22 | 50 | * | 2101-06-20 07:38 | 2.24E-5 | -4.63 | 0 | 13.14 | 2101-2101 | 2.24E-5 | -4.63 | ...
Risk list (special)

URL: PSDB-portlet/download?file=esa_special_risk_list

Output format: same as the normal risk list.

Close approaches (upcoming)

URL: PSDB-portlet/download?file=esa_upcoming_close_app

Output format: a line with the last update date/time, followed by a table of fields delimited by pipe characters (U+007C). The first three lines are headers, with the second field under "diameter" recording an asterisk if the value has been estimated from the absolute magnitude.

Last Update: 2019-10-02 21:24 UTC Object | | Miss Distance | Diameter | H | Max bright | Rel. vel | Num/des. Name | Date | km | au | LD | m | *=Yes | mag | mag | km/s | AAAAAAAAA AAAAAAAAAAAAAAAA | YYYY-MM-DD | DDDDDDD | D.DDDDDD | DD.DDD | NNNN | A | DD.D | DDD.D | DD.D | 2019SL8 | 2019-10-03 | 3023238 | 0.020209 | 7.865 | 26 | * | 25.7 | 18.9 | 27.5 | 2010AE30 | 2020-01-14 | 6905498 | 0.046160 | 17.964 | 50 | | 23.9 | 120 | 51.8 | 162082 1998HL1 | 2019-10-25 | 6216076 | 0.041552 | 16.171 | 500 | * | 19.2 | 12.6 | 19.5 | ...
Close approaches (recent)

URL: PSDB-portlet/download?file=esa_recent_close_app

Output format: same as the upcoming close approaches list.

Priority list (normal)

URL: PSDB-portlet/download?file=esa_priority_neo_list

Output format: a line with the last update date/time, followed by a table of fixed-width fields. There are no headers in the file; the fields are in the order:

  1. Priority class, from 0 (most urgent) to 3 (least)
  2. Designator of the object, quoted
  3. Current right ascension on the sky, Geocentric equatorial, in arcseconds
  4. Current declination on the sky, in sexagesimal degrees
  5. Current Solar elongation, in sexagesimal degrees
  6. Current observable brightness, V band, in magnitudes
  7. Uncertainty in the plane of the sky, in arcseconds
  8. Expected date of end of visibility, quoted and as YYYY/MM/DD
"2019/10/02" 0 "2012 UA174" 8820.0 42.0 134 21.7 18059 "2019/12/23" 0 "2012 VB37" 72840.0 12.7 115 21.0 72229 "2019/11/27" 1 "2019 SG5" 3420.0 -3.3 171 21.7 5 "2019/10/26" ...
Priority list (faint)

URL: PSDB-portlet/download?file=esa_faint_neo_list

Output format: same as the normal priority list.

Direct download of data on an object

These URLs can be invoked with specific object designators. They are equivalent to clicking the Download as TXT button in the relevant tabs of the details page for the object.

Asteroid close approach report

URL: PSDB-portlet/download?file=$desig.clolin

Output format: a table of fixed-width (or space-separated) columns. There are no headers in the file; the fields are the same and in the same order as in the corresponding table in the web portal.

EARTH 1975/01/23.31907 42435.319 0.1511342 0.1511341 5.895E-08 1.353E-08 1.00E+00 EARTH 2012/01/31.45875 55957.459 0.1786758 0.1786758 3.210E-08 7.275E-09 1.00E+00 EARTH 2056/01/24.46037 72021.460 0.1497822 0.1497822 7.077E-08 1.438E-08 1.00E+00 ...
Asteroid observation records

URL: PSDB-portlet/download?file=$desig.rwo

Output format: suitable for input into OrbFit.

version = 2 errmod = 'vfcc17' RMSast = 5.75611E-01 RMSmag = 4.46506E-01 END_OF_HEADER ! Object Obser ============= Date ============= ================== Right Ascension ================= ================= Declination ===================== ==== Magnitude ==== Ast Obs Residual SEL ! Design K T N YYYY MM DD.dddddddddd Accuracy HH MM SS.sss Accuracy RMS F Bias Resid sDD MM SS.ss Accuracy RMS F Bias Resid Val B RMS Resid Cat Cod Chi A M 433 O A 1893 10 29.4132 1.000E-04 06 08 59.320 8.890E-02 5.000 F 0.000 -0.355 +53 39 04.20 1.000E-01 5.000 F 0.000 0.874 802 0.19 1 0 433 O M 1898 08 21.01304 1.000E-05 21 20 41.480 1.492E-01 3.000 F -0.125 2.228 -05 53 51.00 1.000E-01 3.000 F 0.077 -0.438 p 030 0.76 1 0 433 O P 1901 02 06.84085 1.000E-05 04 07 44.800 1.379E-01 5.000 F 0.186 -0.668 +23 10 26.70 1.000E-01 5.000 F -0.790 1.251 m 000 0.28 1 0 433 O C 2 2002 09 22.252272 1.000E-06 22 39 08.317 1.450E-02 0.500 F 0.000 -0.031 +14 46 17.05 1.000E-02 0.500 F 0.000 -0.026 11.28V 0.50 -0.05 g 689 0.08 1 1 433 O C ] 2002 09 27.961458 1.000E-06 22 29 32.708 1.453E-02 0.500 F 0.000 -0.078 +14 19 16.09 1.000E-02 0.500 F 0.000 -0.013 10.7 R 0.70 -0.69 t 950 0.16 1 1 433 S S 2018 07 25.00676 1.000E-05 01 47 20.100 1.388E-01 1.000 F -0.034 0.063 +22 15 12.20 1.000E-01 1.000 F 0.090 0.135 14 R 1.00 0.61 L C51 0.15 1 1 433 S s 2018 07 25.00676 1 2725.7405 5202.6437 3536.8391 C51 433 O C K 2018 09 29.926863 1.000E-06 03 52 55.920 1.056E-01 1.581 F 0.000 -0.153 +45 14 11.60 1.000E-01 1.581 F 0.000 0.197 11.7 G 0.70 0.09 V Z80 0.16 1 1 433 O C 2019 08 28.249222 1.000E-06 14 38 08.930 1.378E-01 1.000 F 0.000 0.079 -23 15 03.30 1.000E-01 1.000 F 0.000 -0.004 13.51o 0.50 -0.47 V T08 0.08 1 1 ! Object Obser ====== Date ======= ============ Radar range/range rate (km or km/d) ============= Station Residual ! Design K T N YYYY MM DD hh:mm:ss Measure Accuracy rms F Bias Resid TRX RCX Chi S 433 V s 1975 01 23 04:25:00 39.15429 90.35605 90.35605 F 0.00000 -83.21717 251 251 0.92 1 433 R c 2012 01 27 06:30:00 26884915.59373 3.74741 3.74741 F 0.00000 -0.13556 253 253 0.04 1
Asteroid orbit properties

URL: PSDB-portlet/download?file=$desig.$orbptype

Output format: OEF as used by OrbFit.

format = 'OEF2.0' ! file format rectype = 'ML' ! record type (1L/ML) refsys = ECLM J2000 ! default reference system END_OF_HEADER 433 ! Keplerian elements: a, e, i, long. node, arg. peric., mean anomaly KEP 1.458248 0.222790 10.830 304.299 178.864 159.138 MJD 58800.0000 TDT MAG 11.073 0.460 ! Non-grav parameters: model used, actual number in use, dimension LSP 0 0 6 ! PERIHELION 1.1334 ! APHELION 1.7831 ! ANODE 0.76863 ! DNODE 0.14964 ! MOID 0.14964 ! PERIOD 643.1989 ! PHA F ! VINFTY 1.2356 ! RMS 2.458E-10 1.016E-08 2.560E-06 1.023E-05 1.130E-05 2.952E-06 COV 6.04292990E-20 9.09209037E-20 -6.17794561E-17 COV -4.00539278E-16 8.81807321E-17 7.72386552E-17 COV 1.03143713E-16 5.47044187E-15 2.15504086E-14 COV -2.26406417E-14 6.22914285E-15 6.55212796E-12 COV 5.12323044E-12 -5.23936067E-12 5.66749789E-13 COV 1.04562491E-10 -1.04403407E-10 4.76487290E-12 COV 1.27648723E-10 -1.84074481E-11 8.71499484E-12 COR 1.00000000 0.03641821 -0.09818138 COR -0.15934314 0.03174985 0.10643326 COR 1.00000000 0.21043106 0.20751341 COR -0.19731455 0.20776546 1.00000000 COR 0.19573331 -0.18116691 0.07500092 COR 1.00000000 -0.90368791 0.15784462 COR 1.00000000 -0.55188905 1.00000000

Generation of observational ephemerides for an object

Asteroid ephemerides for usage by observers: right ascension and declination, apparent motion and other useful information.

URL: PSDB-portlet/ephemerides?des=$desig&oc=$obscode&t0=$tini&t1=$tend&ti=$dt&tiu=$dtunit

Output format: A summary of the parameters used for the query, followed by a table of fixed-width fields.

As an example, using the following parameters: des=433+Eros&oc=500&t0=2019-08-25T00:00Z&t1=2019-09-01T00:00Z&ti=1&tiu=days results in a response similar to the listing below.

Ephemerides generation for: 433 Eros Observatory: 500 - Geocentric Initial Date: 2019/08/25 00:00 UTC Final Date: 2019/09/01 00:00 UTC Time step: 1 days Equatorial coordinates App. motion Date Hour MJD RA DEC Mag Alt Airmass Sun SolEl LunEl Phase Glat Glon R Delta RA*cosDE DEC Sky plane error (UTC) (UTC) h m s d ' " (deg) elev. (deg) (deg) (deg) (deg) (deg) (au) (au) "/min "/min Err1 Err2 PA =========== ====== ============ ============= ============ ===== ===== ======== ====== ====== ====== ====== ===== ===== ======= ======= ======== ======== ======== ======== ===== 25 Aug 2019 0.000 58720.000000 14 29 51.127 -22 56 19.50 14.3 0.0 INF 0.0 -71.4 -143.2 35.7 34.6 330.7 1.643 1.658 1.4699 -0.2444 0.009" 0.008" 165.4 26 Aug 2019 0.000 58721.000000 14 32 24.370 -23 2 9.34 14.3 0.0 INF 0.0 -71.0 -131.0 35.5 34.2 331.3 1.646 1.669 1.4692 -0.2415 0.009" 0.008" 164.4 27 Aug 2019 0.000 58722.000000 14 34 57.653 -23 7 54.90 14.3 0.0 INF 0.0 -70.6 -118.0 35.3 33.9 331.8 1.648 1.679 1.4685 -0.2385 0.009" 0.008" 163.3 ...