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.

All NEA list

URL: PSDB-portlet/download?file=allneo.lst

Output format: the list of all NEOs currently considered in the NEOCC system.

433       Eros
719       Albert
887       Alinda
1036      Ganymed
1221      Amor
1566      Icarus
...
 
Updated NEA list

URL: PSDB-portlet/download?file=updated_nea.lst

Output format: the list of all NEOs updated by NEOCC Orbit Determination system.

# Wed Dec 16 13:00:09 UTC 2020
433           Eros
1036           Ganymed
1685           Toro
1943           Anteros
3199           Nefertiti
...
 
Monthly computation date

URL: PSDB-portlet/download?file=monthly_update.done

Output format: Output format: file containing the date of the latest runs performed by the NEOCC Orbit Determination and Impact Monitoring System using the last MPC Monthly Update information.

Tue Oct 20 19:23:39 UTC 2020
...
 
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.

Impacted objects

URL: PSDB-portlet/download?file=impactedObjectsList.txt

Output format: a table summarising the objects impacted on Earth until now along with their impact date.

2008TC3 2008-10-07
2014AA 2014-01-02
2018LA 2018-06-02
2019MO 2019-06-22
...

 
Close encounter list

URL: PSDB-portlet/download?file=close_encounter2.txt

Output format: file containing the list of all computed close encounters between asteroids and Earth.

Tue  Feb  23  13:13:12  UTC  2021
  Name/desig  |  Planet   |  Date              |  Time  approach   |  Time  uncert     |  Distance               |  Minimum  distance      |  Distance  uncertainty  |  Width      |  Stretch    |  Probability     |  Velocity        |  Max  Mag
  DDDDDDDDDD  |  AAAAA    |  YYYY/MM/DD.DDDDD  |  DDDDD.DDDDDDDDD  |  E.EEEEEEEEEEEEE  |  E.EEEEEEEEEEEEEEEEEEE  |  E.EEEEEEEEEEEEEEEEEEE  |  E.EEEEEEEEEEEEEEEEEEE  |  E.EEEEEEE  |  E.EEEEEEE  |  E.EEEEEE        |  DDD.DDDDDDDD    |  DDD.DDD
         433  |  EARTH    |  1975/01/23.31907  |  42435.319065926  |  1.258310357E-05  |  1.511341757334717E-01  |  1.511341664330519E-01  |  1.905024672273490E-08  |  1.332E-08  |  5.764E-08  |  1.00E+00        |    5.82530920    |    7.390
         433  |  EARTH    |  2012/01/31.45875  |  55957.458754981  |  1.066992942E-05  |  1.786758138376142E-01  |  1.786758137172355E-01  |  7.298809338995028E-09  |  7.232E-09  |  3.059E-08  |  1.00E+00        |    5.94520144    |    8.239
         433  |  EARTH    |  2056/01/24.46037  |  72021.460370451  |  1.470012593E-05  |  1.497821811860041E-01  |  1.497821679409254E-01  |  1.695772121904839E-08  |  1.411E-08  |  6.787E-08  |  1.00E+00        |    5.82076279    |    7.287
...

 

Direct download of data on an objects

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 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

 
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

 
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.

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
...

 
Asteroid close approach report

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

Output format: a table of fixed-width (or space-separated) columns.

 BODY CALENDAR-TIME MJD-TIME TIME-UNCERT. NOM.-DISTANCE MIN.-POSS.-DIST. DIST.-UNCERT. STRETCH WIDTH PROBABILITY
EARTH 1952/11/01.68886 34317.688864607 2.096598257E+01 7.980861285802057E-02 1.821311955041971E-02 4.378308122910667E-01 4.476E-01 4.489E-07 1.48E-01
EARTH 1975/11/06.48625 42722.486247187 2.089669203E+01 1.638756000143885E-01 1.793690962584499E-02 4.845451563848359E-01 4.857E-01 4.202E-07 1.37E-01
...

 
Possible impacts

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

Output format: the first line indicates the object. The following four are header. From the fifth line to the next empty line there are listed all possible impactors. The file ends with some additional information about the orbit determination process and some other comments in html format.

Object: 99942 Apophis

    date             MJD        sigma   sigimp   dist +/- width  stretch     p_RE      exp. en.    PS    TS  
YYYY/MM/DD.ddd                                       (RE)          (RE)      (RE)        (MT)
------------------------------------------------------------------------------------------------------------
 2068-04-12.634    76483.634   -1.317    0.000   1.73 +/- 0.006   3.85E5    1.88E-6    1.43E-3    -3.67   0   
 2068-10-15.324    76669.324   -0.182    0.000   1.48 +/- 0.000   5.29E6    2.39E-7    1.81E-4    -4.57   0   
 2069-04-13.079    76849.079    4.127    0.000   1.68 +/- 0.000   1.67E5    1.80E-9    1.36E-6    -6.70   0   
 2069-10-15.604    77034.604    1.993    0.000   1.85 +/- 0.000   3.34E6    6.56E-8    4.97E-5    -5.14   0   
 2069-10-15.973    77034.973    2.543    0.000   0.46 +/- 0.016   9.20E5    7.23E-8    5.49E-5    -5.09   0   
 2077-04-13.165    79771.165    4.205    0.000   2.14 +/- 0.000   1.03E6    1.34E-10   1.02E-7    -7.88   0   
 2078-04-13.442    80136.442    4.125    0.000   1.61 +/- 0.000   6.23E6    4.32E-11   3.27E-8    -8.38   0   
 2102-04-11.809    88899.809    2.556    0.000   4.22 +/- 0.253   1.85E7    2.96E-9    2.18E-6    -6.68   0   
 2106-10-16.871    90548.871    2.540    0.000   2.03 +/- 0.000   6.53E5    3.88E-8    2.94E-5    -5.57   0   
 2116-04-15.650    94017.650    1.989    0.000   2.14 +/- 0.000   3.10E9    3.63E-11   1.44E-8    -8.87   0   

Based on 4105 optical observations (of which  87 are rejected as outliers)
from 2004/03/15.109 to 2013/05/07.150.

Coordinates are given on the Target Plane

Unit is one Earth radius, but impact cross section
has radius between  2.15 and  2.15 Earth radii

Coordinates for LOV = KEP scaled= T second= F

OrbFit software version= 4.3, 08/05/2012 Date of computation=20130801 220340.613 CET

<p> </p>
<p><span style="color: #0000CD;"><strong>ADDITIONAL NOTE</strong></span></p>
<p>The results contained in this impactor table are based on the Line Of Variations method generalised
to the 7-dimensional space of the orbital elements and the Yarkovsky parameter. The Yarkovsky parameter
has been estimated from the fit to the astrometry as (5.98 +/- 2.06) 10<sup>-15</sup> au/d<sup>2</sup>,
so that no a priori constraint based upon models and physical observations has been used.<p>

<p>The results are qualitatively compatible with the ones obtained at JPL, computed by using a priori
information for the Yarkovsky effect computation and a Monte Carlo method, as described in the paper
<a href="http://arxiv.org/abs/1301.1607" target="_blank">Farnocchia <em>et al.</em> (2013)</a>.</p>