ObjectLookup Service
The NASA/IPAC Extragalactic Database (NED) has developed a service called ObjectLookup
which has replaced the venerable nedsrv providing astronomical object name interpretation, NED standard form, and essential information. The new ObjectLookup service is integrated with the evolving NED system and can be accessed over an encrypted (https, SSL) connection if desired. Further, results/reports are kept compact and concise which improves performance, and may reduce latency. Below are some examples demonstrating the use of ObjectLookup.
Since the very early days in 1994, NED has provided a service to resolve or interpret strings as astronomical object names. Such services are fundamental to archives providing catalog queries, image, spectra, and other detail requests for data collected about these objects. Today, such name-resolver services are even more crucial to data-center and archive interoperability and to world-wide virtual observatory efforts.
The first NED gateway service (sometimes referred to as an API) called nedsrv, accepted a TCP/IP connection, listens for a simple command string followed by a string to be interpreted. (Note that NED was created in 1990 and pre-dates the 1996 issue of IETF RFC-1945 Hypertext Transfer Protocol↗ describing HTTP.) The input string is resolved, if possible, into a canonical or well-known object name with references in the NED database of extragalactic objects. The service responded with the proper/preferred name of the object if it can be determined, followed by essential information if the object is listed in NED. The nedsrv report was untagged line-oriented format. After over 2 decades of operation, the classic, widely used, service, became ever more difficult to operate with the performance, security, and reliability required by the global astronomy research community. nedsrv is now replaced with ObjectLookup.
The new NED ObjectLookup service is designed to communicate over an HTTP connection, behind a high performance web server, using a modern serialization protocol (JSON). This allows the new service to be integrated with the evolving NED system; to be accessed over an encrypted (SSL) connection if desired; for reports to be kept small for routine requests, (lower network delays with hopefully better performance); and, still provide additional detailed information if requested.
It is important to note, that at this time the output of ObjectLookup (report or returned result) is always
a compact JSON (http://www.json.org/, IETF RFC-4627) stream. JSON is a data serialization format that is hierarchical but unordered, and is not intended for casual viewing. Speed and data-system interoperability are our goals. Human User Interfaces such as NED's 'by-name' query (https://ned.ipac.caltech.edu/forms/byname.html), or new human user interface (https://ned.ipac.caltech.edu) are far friendlier to human viewers.
The URL
The service URL for ObjectLookup is:
https://ned.ipac.caltech.edu/srs/ObjectLookup
The Query
There is only one type of query: "name".
The input is expected to be a JSON block with this variable name, and a string value,
which the NED Name Interpreter will attempt to resolve to a known NED object, and essential identifying data.
Additional, qualifiers, and query parameters are illustrated in the examples below.
E.g.:
{"name":{"v":"ARP 319"}}
The Results
There are three 'normal' / Successful (StatusCode=100) results:
{..., "ResultCode": 0 } Not an object name: the supplied string could not be interpreted as the as a valid object name.
{..., "ResultCode": 1 } Ambiguous name: the input was a valid but unspecific name: a list of possibly intended aliases is return. NOTE: that the aliases themselves my still be ambiguous - be prepared to iterate with your user.
{..., "ResultCode": 2 } Valid name: the input provided was interpreted as a proper object name, but there is no such object known in NED (it may be very new, or we may the NED standard form is returned.
{..., "ResultCode": 3 } Known name: the input provided was interpreted as a proper object name that was known to NED. Essential details are provided in the report.
Versioning
The current version of ObjectLookup is reported in the response. Changes to the right-hand (minor) version, indicate a backward compatible change, e.g. a addition of a key to the JSON structure. Changes to the left-hand (major) version indicate a change that may include a schema change that is not compatible with older clients. Client implementations should check the 'Version' string of the default output where compatibility is of concern (probably always except during testing).
Use and Acknowledgment
Questions about access to ObjectLookup may be sent to the NED Helpdesk
[email protected]
If you use NED to augment or operate an online service, or if research benefits from the use of the NED database, the following acknowledgement in your paper, or prominently in your application or online service, would be appreciated: This research has made use of the NASA/IPAC Extragalactic Database (NED) which is operated California Institute of Technology, under contract with the National Aeronautics and Space Administration.
The ability of NED to support and keep pace with automated access, involving large data volumes and/or high query rates is limited. Such support is provided on an as-available, best-effort basis. Our goal is to provide fair use and responsive access to NED resources for the entire astronomical community as well as the general public.
For more information, see
NED Guidelines for Automated Queries.
Examples of Use
We use the fairly ubiquitous command-line utility "curl" here, to
demonstrate queries using
RFC-2616 HTTP/1.1. Using a current, high-quality library or module for
your language/system of choice.
Query examples/how to use curl:
% curl -k -s -X POST --data 'json={"name":{"v":"abc"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
% curl -s -X POST --data 'json={"name":{"v":"abc"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
curl -s -H "Accept: application/json" -X POST --data @q.json https://ned.ipac.caltech.edu/srs/ObjectLookup
Where the file q.json contains the single line: json={"name":{"v":"ARP 319"}}
curl "https://ned.ipac.caltech.edu/srs/ObjectLookup?name=Stephan%27s%20Quintet"
curl -F "name=Stephan's Quintet" https://ned.ipac.caltech.edu/srs/ObjectLookup
Query examples with result examples of the 4 result code types
In the following examples, the
Result: may be formatted for readability and presentation.
ObjectLookup returns JSON in compact form.
Query (ResultCode 0 example):
% curl -k -s -X POST --data 'json={"name":{"v":"abc"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{"QueryTime": "Fri Feb 24 17:28:50 2017", "NameResolver": "NED-Egret", "Copyright": "(C) 2017 California Institute of Technology", "Supplied": "abc", "Version": "2.0", "StatusCode": 100, "ResultCode": 0}
Query (ResultCode 1 example):
% curl -s -X POST --data 'json={"name":{"v":"andromeda"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{
"QueryTime": "Fri Feb 24 17:30:09 2017",
"Copyright": "(C) 2017 California Institute of Technology",
"Supplied": "andromeda",
"Version": "2.0",
"Interpreted": {
"Aliases": [
"ANDROMEDA GALAXY",
"ANDROMEDA I",
"ANDROMEDA II",
"ANDROMEDA III",
"ANDROMEDA IV",
"ANDROMEDA V",
"ANDROMEDA VI",
"ANDROMEDA VII",
"ANDROMEDA VIII",
"ANDROMEDA IX",
"ANDROMEDA X",
"ANDROMEDA XI",
"ANDROMEDA XII",
"ANDROMEDA XIII",
"ANDROMEDA XIV",
"ANDROMEDA XV",
"ANDROMEDA XVI",
"ANDROMEDA XVII",
"ANDROMEDA XVIII",
"ANDROMEDA XIX",
"ANDROMEDA XX",
"ANDROMEDA XXI",
"ANDROMEDA XXII",
"ANDROMEDA XXIII",
"ANDROMEDA XXIV",
"ANDROMEDA XXV",
"ANDROMEDA XXVI",
"ANDROMEDA XXVII",
"ANDROMEDA XXVIII",
"ANDROMEDA XXIX",
"ANDROMEDA XXX",
"ANDROMEDA XXXI",
"ANDROMEDA XXXII",
"ANDROMEDA XXXIII",
"Andromeda GROUP"
]
},
"NameResolver": "NED-Egret",
"StatusCode": 100,
"ResultCode": 1
}
Query (ResultCode 2 example):
% curl -k -s -X POST --data 'json={"name":{"v":"SN1999"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{"QueryTime": "Fri Feb 24 17:32:51 2017", "Interpreted": {"Name": "SN 1999"},
"Copyright": "(C) 2017 California Institute of Technology",
"NameResolver": "NED-Egret", "StatusCode": 100, "Version": "2.0",
"Message": "Unknown name", "Supplied": "SN1999", "ResultCode": 2}
Query (ResultCode 3 example):
% curl -s -X POST --data 'json={"name":{"v":"m31"}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{
"QueryTime": "Fri Feb 24 17:34:40 2017",
"ResultCode": 3,
"Copyright": "(C) 2017 California Institute of Technology",
"Version": "2.0",
"StatusCode": 100,
"Interpreted": {
"Name": "MESSIER 031"
},
"Supplied": "m31",
"NameResolver": "NED-Egret",
"Preferred": {
"Redshift": {
"Value": -0.00100100006,
"Uncertainty": 1.29999999e-05,
"RefCode": "1991RC3.9.C...0000d",
"QualityFlag": null
},
"Name": "MESSIER 031",
"Position": {
"RA": 10.68479292,
"Dec": 41.269065,
"PosAngle": 0,
"UncSemiMinor": 2.222222222e-05,
"UncSemiMajor": 2.222222222e-05,
"RefCode": "2010ApJS..189...37E"
},
"ObjType": {
"Value": "G",
"RefCode": null
}
}
}
Additional query examples demonstrating new aliases and types options
Aliases
% curl -s -X POST --data 'json={"name":{"v":"m31"},"aliases":{"v":true}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{
"QueryTime": "Mon Feb 27 11:53:11 2017",
"Interpreted": {
"Name": "MESSIER 031"
},
"Copyright": "(C) 2017 California Institute of Technology",
"Version": "2.0",
"ResultCode": 3,
"Preferred": {
"Name": "MESSIER 031",
"ObjType": {
"RefCode": null,
"Value": "G"
},
"Position": {
"RA": 10.68479292,
"Dec": 41.269065,
"UncSemiMinor": 2.222222222e-05,
"UncSemiMajor": 2.222222222e-05,
"RefCode": "2010ApJS..189...37E",
"PosAngle": 0
},
"Redshift": {
"RefCode": "1991RC3.9.C...0000d",
"Value": -0.00100100006,
"Uncertainty": 1.29999999e-05,
"QualityFlag": null
}
},
"Supplied": "m31",
"NameResolver": "NED-Egret",
"StatusCode": 100,
"Aliases": [
"MESSIER 031",
"NGC 0224",
"Andromeda Galaxy",
"UGC 00454",
"CGCG 535-017",
"CGCG 0040.0+4100",
"MCG +07-02-016",
"GIN 801",
"B3 0040+409",
"2MASX J00424433+4116074",
"IRAS 00400+4059",
"IRAS F00400+4059",
"KTG 01C",
"LDCE 0031 NED007",
"HDCE 0029 NED003",
"LQAC 010+041 001",
"HOLM 017A",
"PGC 002557",
"UZC J004244.3+411608",
"11HUGS 013",
"87GB 004002.2+405940",
"87GB[BWE91] 0040+4059",
"6C B004001.6+410004",
"MY 0040+409A",
"CXO J004244.2+411608",
"CXO J004244.3+411608",
"CXOM31 J004244.3+411608",
"RX J0042.6+4115",
"1RXS J004241.8+411535",
"MAXI J0043+410",
"2PBC J0042.6+4111",
"XMMLPt 1010",
"XMMM31 J004244.1+411607",
"2XMMp J004244.4+411612",
"2XMM J004244.5+411611",
"EXSS 0039.9+4059",
"1H 0039+408",
"1ES 0039+409",
"XSS J00425+4102",
"2FGL J0042.5+4114",
"[PFJ93] 44",
"[SPB93] 010",
"LGG 011:[G93] 001",
"[MHH96] J004241+411531",
"[VCV2001] J004244.3+411610",
"MESSIER 031:[KGP2002] r1-010",
"MESSIER 031:[PFH2005] 321",
"MESSIER 031:[VG2007] 001",
"LEDA 002557",
"0039+408",
"0040+4059"
]
}
NameTypes
% curl -s -X POST --data 'json={"name":{"v":"m31"},"types":{"v":true}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Result:
{
"ResultCode": 3,
"QueryTime": "Mon Feb 27 11:53:23 2017",
"StatusCode": 100,
"Copyright": "(C) 2017 California Institute of Technology",
"Version": "2.0",
"Preferred": {
"ObjType": {
"Value": "G",
"RefCode": null
},
"Name": "MESSIER 031",
"Position": {
"UncSemiMajor": 2.222222222e-05,
"RA": 10.68479292,
"PosAngle": 0,
"Dec": 41.269065,
"UncSemiMinor": 2.222222222e-05,
"RefCode": "2010ApJS..189...37E"
},
"Redshift": {
"Uncertainty": 1.29999999e-05,
"Value": -0.00100100006,
"RefCode": "1991RC3.9.C...0000d",
"QualityFlag": null
}
},
"Supplied": "m31",
"NameResolver": "NED-Egret",
"Interpreted": {
"Name": "MESSIER 031"
},
"NameTypes": [
"G",
"G",
"G",
"G",
"G",
"G",
"G",
"G",
"RadioS",
"IrS",
"IrS",
"IrS",
"G",
"G",
"G",
"QSO",
"G",
"G",
"G",
"G",
"RadioS",
"RadioS",
"RadioS",
"RadioS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"GammaS",
"XrayS",
"G",
"G",
"XrayS",
"G",
"V*",
"XrayS",
"XrayS",
"G",
"Other",
"Other"
]
}
Aliases & NameTypes
% curl -s -X POST --data 'json={"name":{"v":"m31"},"aliases":{"v":true},"types":{"v":true}}' https://ned.ipac.caltech.edu/srs/ObjectLookup
Note that indexes in the array of nameTypes, and the array of Names correspond.
The first nameType element, is the nameType associated with the first Name element.
Result:
{
"QueryTime": "Mon Feb 27 11:53:52 2017",
"Supplied": "m31",
"Preferred": {
"Redshift": {
"Value": -0.00100100006,
"Uncertainty": 1.29999999e-05,
"RefCode": "1991RC3.9.C...0000d",
"QualityFlag": null
},
"ObjType": {
"Value": "G",
"RefCode": null
},
"Name": "MESSIER 031",
"Position": {
"RefCode": "2010ApJS..189...37E",
"RA": 10.68479292,
"Dec": 41.269065,
"UncSemiMajor": 2.222222222e-05,
"UncSemiMinor": 2.222222222e-05,
"PosAngle": 0
}
},
"Copyright": "(C) 2017 California Institute of Technology",
"Version": "2.0",
"NameTypes": [
"G",
"G",
"G",
"G",
"G",
"G",
"G",
"G",
"RadioS",
"IrS",
"IrS",
"IrS",
"G",
"G",
"G",
"QSO",
"G",
"G",
"G",
"G",
"RadioS",
"RadioS",
"RadioS",
"RadioS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"XrayS",
"GammaS",
"XrayS",
"G",
"G",
"XrayS",
"G",
"V*",
"XrayS",
"XrayS",
"G",
"Other",
"Other"
],
"NameResolver": "NED-Egret",
"StatusCode": 100,
"Interpreted": {
"Name": "MESSIER 031"
},
"ResultCode": 3,
"Aliases": [
"MESSIER 031",
"NGC 0224",
"Andromeda Galaxy",
"UGC 00454",
"CGCG 535-017",
"CGCG 0040.0+4100",
"MCG +07-02-016",
"GIN 801",
"B3 0040+409",
"2MASX J00424433+4116074",
"IRAS 00400+4059",
"IRAS F00400+4059",
"KTG 01C",
"LDCE 0031 NED007",
"HDCE 0029 NED003",
"LQAC 010+041 001",
"HOLM 017A",
"PGC 002557",
"UZC J004244.3+411608",
"11HUGS 013",
"87GB 004002.2+405940",
"87GB[BWE91] 0040+4059",
"6C B004001.6+410004",
"MY 0040+409A",
"CXO J004244.2+411608",
"CXO J004244.3+411608",
"CXOM31 J004244.3+411608",
"RX J0042.6+4115",
"1RXS J004241.8+411535",
"MAXI J0043+410",
"2PBC J0042.6+4111",
"XMMLPt 1010",
"XMMM31 J004244.1+411607",
"2XMMp J004244.4+411612",
"2XMM J004244.5+411611",
"EXSS 0039.9+4059",
"1H 0039+408",
"1ES 0039+409",
"XSS J00425+4102",
"2FGL J0042.5+4114",
"[PFJ93] 44",
"[SPB93] 010",
"LGG 011:[G93] 001",
"[MHH96] J004241+411531",
"[VCV2001] J004244.3+411610",
"MESSIER 031:[KGP2002] r1-010",
"MESSIER 031:[PFH2005] 321",
"MESSIER 031:[VG2007] 001",
"LEDA 002557",
"0039+408",
"0040+4059"
]
}
The best way to provide input to NED, on any of our services or plans, is to contact us via the NED Helpdesk or direct email to [email protected]
