如何构建新闻 API使用 MarkUDown
三个端点,两个 Python 依赖。一个通过 RSS 和网站映射发现文章、提取每篇内容,并返回包含来源、标题、副标题、日期、作者和正文的结构化 JSON 的流水线——来自任何门户,无需维护 CSS 选择器。
每个数据分析师都遇到过的问题
你需要了解媒体对你所在行业的报道。可能是一个投资基金监控投资组合公司的报道。一家追踪竞争对手提及的初创公司。一个衡量产品发布影响的营销团队。一个构建经济新闻语料库的研究员。
听起来像个简单的问题。你有 URL。你有 Python。你打开终端,从 requests.get(url).text 开始。
然后现实来了:
- G1 返回文章为空的 HTML——内容通过 JavaScript 加载
- Folha 从数据中心 IP 返回 403
- InfoMoney 每次重新设计后结构都不同
- 你提取了文本,但菜单、广告和页脚也一起来了
- 每个门户对日期、作者和副标题使用不同的格式
看起来像下午的脚本变成了一个持续维护的项目。你修复 G1 选择器,Valor 改变了布局,你修复 Valor,Folha 更新了反机器人,循环重新开始。
三个端点。问题解决。
MarkUDown 有三个端点,共同覆盖整个新闻流水线:
/rss — 从 feed 发现
传入任何 RSS feed 的 URL。获取回每篇文章的 {url, title, summary} 数组。无需库,无需手动 XML 解析。
/map — 在没有 RSS 的门户发现
对于不提供 feed 的网站,/map 爬取栏目页面并返回文章 URL。URL 模式过滤器只隔离文章。
/extract — 一次调用结构化提取
传入文章 URL 和字段 schema。端点访问页面、提取干净内容,并用 AI 映射字段——返回即用的 JSON。
包含反机器人门户
教程
你需要一个 MarkUDown API key。在控制台免费创建你的。
创建账户并获取 API key
访问 MarkUDown 控制台,创建免费账户并复制你的 API key。它以 header X-API-KEY 的形式用于所有调用。
安装依赖
只需两个 Python 库:
pip install requests python-dotenv在根目录创建 .env :
# .env
MARKUDOWN_API_KEY=sua_chave_aqui永远不要提交你的 API key
定义新闻 schema
schema 是一个描述你想提取的字段的字典。AI 使用这些描述来理解在每个页面上寻找什么——与门户的布局无关。
NEWS_SCHEMA = {
"fonte": "Nome do portal ou veículo de comunicação",
"titulo": "Título principal da matéria",
"subtitulo": "Subtítulo ou linha de apoio, se existir",
"data_publicacao": "Data e hora de publicação no formato ISO 8601",
"autor": "Nome do autor ou repórter",
"texto": "Corpo completo da matéria, sem anúncios ou menus",
}阶段 1 — 通过 /rss 发现
对于有 RSS feed 的门户,一次 /rss 调用就能返回所有最近的文章,包含 URL、标题和摘要。无需解析库,无需处理 XML。
import requests
import os
MARKUDOWN_API_KEY = os.getenv("MARKUDOWN_API_KEY")
BASE_URL = "https://api.scrapetechnology.com"
def descobrir_via_rss(feed_url: str) -> list[dict]:
"""Retorna lista de {url, title, summary} para cada item do feed."""
resp = requests.post(
f"{BASE_URL}/rss",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={"url": feed_url},
timeout=30,
)
resp.raise_for_status()
return resp.json().get("items", [])
feeds = [
"https://g1.globo.com/rss/g1/economia/",
"https://feeds.folha.uol.com.br/mercado/rss091.xml",
"https://www.infomoney.com.br/feed/",
"https://www.valor.com.br/rss",
]
itens = []
for feed_url in feeds:
novos = descobrir_via_rss(feed_url)
itens.extend(novos)
print(f" {feed_url}: {len(novos)} matérias")RSS 优先,始终如此
阶段 1b — 通过 /map 发现
对于没有 RSS feed 的门户,/map 爬取栏目页面并返回找到的 URL。filter_pattern 只过滤遵循文章模式的 URL(路径中有年份)。
def descobrir_via_map(site_url: str, max_urls: int = 50) -> list[str]:
resp = requests.post(
f"{BASE_URL}/map",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={
"url": site_url,
"limit": max_urls,
"filter_pattern": "/[0-9]{4}/", # filtra URLs com ano no caminho
},
timeout=30,
)
resp.raise_for_status()
return resp.json().get("urls", [])
# Portais sem feed RSS
portais_sem_rss = [
"https://www.cnnbrasil.com.br/economia/",
]
for portal in portais_sem_rss:
urls = descobrir_via_map(portal)
itens.extend([{"url": u} for u in urls])
print(f" {portal}: {len(urls)} URLs")阶段 2 — 使用 /extract 提取
对于每个发现的 URL,一次 /extract 调用完成一切:访问页面、渲染 JavaScript、删除噪音(广告、菜单、页脚)并将内容映射到你的 schema 字段。
def extrair_materia(url: str) -> dict | None:
try:
resp = requests.post(
f"{BASE_URL}/extract",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={
"url": url,
"schema_fields": NEWS_SCHEMA,
"extract_query": "Extraia os detalhes completos desta matéria jornalística",
},
timeout=60,
)
resp.raise_for_status()
body = resp.json()
if not body.get("success") or not body.get("data"):
return None
result = body["data"]
result["url"] = url
return result
except requests.RequestException as e:
print(f" ✗ {url}: {e}")
return None完整流水线
将两个阶段合并成一个端到端运行的脚本:
"""
Pipeline de coleta e extração de notícias com MarkUDown.
Uso:
python news_pipeline.py
Saída:
noticias.json
"""
import json, time, os, requests
from datetime import datetime
from dotenv import load_dotenv
load_dotenv()
MARKUDOWN_API_KEY = os.getenv("MARKUDOWN_API_KEY")
BASE_URL = "https://api.scrapetechnology.com"
NEWS_SCHEMA = {
"fonte": "Nome do portal ou veículo de comunicação",
"titulo": "Título principal da matéria",
"subtitulo": "Subtítulo ou linha de apoio, se existir",
"data_publicacao": "Data e hora de publicação no formato ISO 8601",
"autor": "Nome do autor ou repórter",
"texto": "Corpo completo da matéria, sem anúncios ou menus",
}
RSS_FEEDS = [
"https://g1.globo.com/rss/g1/economia/",
"https://feeds.folha.uol.com.br/mercado/rss091.xml",
"https://www.infomoney.com.br/feed/",
"https://www.valor.com.br/rss",
]
SITES_SEM_RSS = [
"https://www.cnnbrasil.com.br/economia/",
]
# ── Fase 1: Descoberta ────────────────────────────────────────────────────────
def descobrir_urls() -> list[str]:
urls = []
print("→ Fase 1: Descoberta de URLs")
for feed_url in RSS_FEEDS:
try:
resp = requests.post(
f"{BASE_URL}/rss",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={"url": feed_url},
timeout=30,
)
resp.raise_for_status()
itens = resp.json().get("items", [])
novos = [item["url"] for item in itens if item.get("url")]
urls.extend(novos)
print(f" RSS {feed_url[:55]}: {len(novos)} matérias")
except requests.RequestException as e:
print(f" ✗ RSS {feed_url}: {e}")
for site in SITES_SEM_RSS:
try:
resp = requests.post(
f"{BASE_URL}/map",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={"url": site, "limit": 30, "filter_pattern": "/[0-9]{4}/"},
timeout=30,
)
resp.raise_for_status()
novos = resp.json().get("urls", [])
urls.extend(novos)
print(f" Map {site[:55]}: {len(novos)} URLs")
except requests.RequestException as e:
print(f" ✗ Map {site}: {e}")
seen, unique = set(), []
for url in urls:
if url not in seen:
seen.add(url)
unique.append(url)
print(f"\n Total: {len(unique)} URLs únicas\n")
return unique
# ── Fase 2: Extração ──────────────────────────────────────────────────────────
def extrair_materia(url: str) -> dict | None:
try:
resp = requests.post(
f"{BASE_URL}/extract",
headers={"X-API-KEY": MARKUDOWN_API_KEY},
json={
"url": url,
"schema_fields": NEWS_SCHEMA,
"extract_query": "Extraia os detalhes completos desta matéria jornalística",
},
timeout=60,
)
resp.raise_for_status()
body = resp.json()
if not body.get("success") or not body.get("data"):
return None
result = body["data"]
result["url"] = url
return result
except requests.RequestException:
return None
def extrair_todas(urls: list[str], delay: float = 1.0) -> list[dict]:
print("→ Fase 2: Extração das matérias")
resultados = []
for i, url in enumerate(urls, 1):
print(f" [{i:02d}/{len(urls)}] {url[:70]}...", end=" ", flush=True)
materia = extrair_materia(url)
if materia:
resultados.append(materia)
print(f"✓ {materia.get('titulo', '')[:45]}...")
else:
print("✗ skipped")
time.sleep(delay)
print(f"\n Extraídas com sucesso: {len(resultados)}/{len(urls)}\n")
return resultados
# ── Main ──────────────────────────────────────────────────────────────────────
def main():
start = datetime.now()
urls = descobrir_urls()
noticias = extrair_todas(urls[:20]) # remova [:20] para processar tudo
output_path = "noticias.json"
with open(output_path, "w", encoding="utf-8") as f:
json.dump(noticias, f, ensure_ascii=False, indent=2)
elapsed = (datetime.now() - start).total_seconds()
print(f"✓ {len(noticias)} notícias salvas em '{output_path}' ({elapsed:.1f}s)")
if __name__ == "__main__":
main()运行
python news_pipeline.py脚本实时打印进度,最后保存 noticias.json。
结果
每篇文章变成一个干净的 JSON 对象——可以索引、用 LLM 处理、供给控制台或通过自己的 API 发布:
[
{
"fonte": "InfoMoney",
"titulo": "Ibovespa sobe 1,2% e fecha a 128.450 pontos com alívio externo",
"subtitulo": "Bolsa acompanhou recuperação dos mercados internacionais após dados de inflação nos EUA",
"data_publicacao": "2026-04-14T18:32:00-03:00",
"autor": "Redação InfoMoney",
"texto": "O Ibovespa, principal índice da bolsa brasileira, encerrou a sessão desta segunda-feira em alta de 1,2%, aos 128.450 pontos. O movimento seguiu a recuperação dos mercados internacionais...",
"url": "https://www.infomoney.com.br/mercados/ibovespa-sobe-128450-pontos/"
},
{
"fonte": "Folha de S.Paulo",
"titulo": "Banco Central mantém Selic em 10,5% ao ano pela segunda reunião seguida",
"subtitulo": "Decisão unânime do Copom surpreendeu parte do mercado que esperava corte de 0,25 ponto",
"data_publicacao": "2026-04-13T21:00:00-03:00",
"autor": "Eduardo Cucolo",
"texto": "O Comitê de Política Monetária (Copom) do Banco Central manteve a taxa Selic em 10,5% ao ano...",
"url": "https://www1.folha.uol.com.br/mercado/2026/04/banco-central-mantem-selic.shtml"
}
]用这个可以构建什么
提及监控
检测你的公司、产品或竞争对手何时在媒体中被提及。每小时运行流水线。
自定义主题 feed
将来自多个按行业过滤的来源的新闻聚合到一个端点——无需手动打开每个门户。
情感分析
将文本字段传给 LLM 分类为正面、中性或负面。大规模衡量品牌认知。
编辑控制台
用已规范化的当天文章供给内部面板。无需复制粘贴。
趋势警报
比较一段时间内的报道量和情感。识别某个话题何时开始升温。
AI 语料库
构建真实新闻数据库来训练语言模型、embeddings 或 RAG 系统。