Nasa Ads ApiSAFE

🔬 A curated collection of 23,000+ agent skills for empirical research across 8 social science disciplines. | 精选 23,000+ AI Agent 技能库,覆盖8大社会科学学科的实证研究。CoPaper.AI 20分钟完成一篇可复现的规范实证论文,并支持用户上传 Skills。-- Maintained by CoPaper.AI from Stanford REAP.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: nasa-ads-api
description: "Search astrophysics and physics literature via NASA ADS bibliographic database"
metadata:
  openclaw:
    emoji: "🔍"
    category: "domains"
    subcategory: "physics"
    keywords: ["astrophysics", "observational astronomy", "cosmology", "high energy physics"]
    source: "https://ui.adsabs.harvard.edu/help/api/"
    requires:
      env: ["ADS_API_TOKEN"]
---

# NASA ADS API Guide

## Overview

The NASA Astrophysics Data System (ADS) is a digital library operated by the Smithsonian Astrophysical Observatory under a NASA grant. It is the primary bibliographic database for astronomy and astrophysics, also covering significant portions of physics, geophysics, and related disciplines. ADS indexes over 16 million records and provides access to full-text articles, citations, and usage metrics.

ADS is indispensable for astronomers and physicists. Nearly every paper in astrophysics is indexed in ADS, and the system provides powerful search capabilities including full-text search, citation and reference tracking, author disambiguation, and object-level queries (search by astronomical object name). The database integrates with SIMBAD, NED, and other astronomical databases to link publications to the celestial objects they study.

The ADS API requires a free API token and supports 3,000 requests per day. It returns JSON and supports a rich query language with field-specific searches, boolean operators, and positional queries.

## Authentication

Authentication is required via a free API token. Register at https://ui.adsabs.harvard.edu/user/settings/token to generate your token. Include it in every request as a header:

```
Authorization: Bearer YOUR_ADS_API_TOKEN
```

Tokens do not expire but can be regenerated from the settings page. Each token is associated with a user account and is subject to per-account rate limits.

## Core Endpoints

### Query: Search the ADS Database

- **URL**: `GET https://api.adsabs.harvard.edu/v1/search/query`
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | q | string | Yes | Search query (ADS query syntax with field qualifiers) |
  | fl | string | No | Fields to return (comma-separated: title, author, year, bibcode, doi, citation_count, abstract, etc.) |
  | rows | integer | No | Results per page (default: 10, max: 2000) |
  | start | integer | No | Pagination offset (default: 0) |
  | sort | string | No | Sort field and order (e.g., citation_count desc, date desc) |
  | fq | string | No | Filter queries for faceting (e.g., database:astronomy) |
- **Example**:
  ```bash
  curl -H "Authorization: Bearer YOUR_TOKEN" \
       "https://api.adsabs.harvard.edu/v1/search/query?q=gravitational+waves&fl=title,author,year,bibcode,citation_count,doi&rows=10&sort=citation_count+desc"
  ```
- **Response**: JSON with `response.numFound` (total hits) and `response.docs` array. Each doc contains the requested fields. The `bibcode` is the unique ADS identifier (19-character string encoding journal, year, volume, and page).

### Author Search: Find Researcher Publications

- **URL**: `GET https://api.adsabs.harvard.edu/v1/search/query`
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | q | string | Yes | Author query using author: or first_author: fields |
  | fl | string | No | Fields to return |
  | rows | integer | No | Results per page |
  | sort | string | No | Sort order |
- **Example**:
  ```bash
  curl -H "Authorization: Bearer YOUR_TOKEN" \
       "https://api.adsabs.harvard.edu/v1/search/query?q=author:%22Hawking,+S%22&fl=title,year,bibcode,citation_count&rows=20&sort=citation_count+desc"
  ```
- **Response**: JSON with matching publications by the specified author.

### Object Search: Find Papers About Astronomical Objects

- **URL**: `GET https://api.adsabs.harvard.edu/v1/search/query`
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | q | string | Yes | Object query using object: field (e.g., object:"M31") |
  | fl | string | No | Fields to return |
  | rows | integer | No | Results per page |
- **Example**:
  ```bash
  curl -H "Authorization: Bearer YOUR_TOKEN" \
       "https://api.adsabs.harvard.edu/v1/search/query?q=object:%22Sgr+A*%22&fl=title,author,year,bibcode,citation_count&rows=10&sort=date+desc"
  ```
- **Response**: JSON with publications related to the specified astronomical object.

### Metrics: Paper and Author Metrics

- **URL**: `POST https://api.adsabs.harvard.edu/v1/metrics`
- **Parameters**:
  | Param | Type | Required | Description |
  |-------|------|----------|-------------|
  | bibcodes | array | Yes | Array of ADS bibcodes (JSON body) |
  | types | array | No | Metric types: basic, citations, indicators, histograms |
- **Example**:
  ```bash
  curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
       -H "Content-Type: application/json" \
       "https://api.adsabs.harvard.edu/v1/metrics" \
       -d '{"bibcodes": ["2016PhRvL.116f1102A"], "types": ["basic", "citations", "indicators"]}'
  ```
- **Response**: JSON with citation metrics, h-index, g-index, read counts, and citation histograms for the specified papers.

## Rate Limits

The API allows 3,000 requests per day (resets at midnight UTC) and 15 requests per second burst limit. If limits are exceeded, the API returns HTTP 429 with `X-RateLimit-Reset` header. For large bibliometric analyses, use the ADS bulk export or the myADS notification system. Monitor usage via `X-RateLimit-Remaining` response headers.

## Common Patterns

### Literature Review in Astrophysics

Search for recent highly-cited papers on a topic:

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://api.adsabs.harvard.edu/v1/search/query?q=dark+energy+AND+year:2023-2026&fl=title,author,year,bibcode,citation_count,doi,abstract&rows=20&sort=citation_count+desc"
```

### Build an Author's Publication 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.