---
name: ucdp-api-ingestion
description: "How to get UCDP Conflict Data API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load one UCDP GED page into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/ucdp-api
Provider: https://ucdp.uu.se/apidocs/
Checked against the provider's documentation: 2026-11-01

## Access
- Request a free access token from the API maintainer and briefly describe the intended use; UCDP says review takes three to five working days.
- Set UCDP_API_TOKEN and send it in the x-ucdp-access-token header.

## Request
```bash
curl -H "x-ucdp-access-token: $UCDP_API_TOKEN" 'https://ucdpapi.pcr.uu.se/api/gedevents/26.1?pagesize=100&page=1'
```

## Format
Paginated JSON with TotalCount, TotalPages, page URLs and Result records containing event IDs, actors, country and administrative areas, latitude and longitude, date ranges, violence type, sources and fatality estimates.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""One page of UCDP GED 26.1 events -> pandas -> Parquet."""
import os
import requests
import pandas as pd

URL = "https://ucdpapi.pcr.uu.se/api/gedevents/26.1"
headers = {"x-ucdp-access-token": os.environ["UCDP_API_TOKEN"]}
params = {"pagesize": 100, "page": 1}
r = requests.get(URL, headers=headers, params=params, timeout=60)
r.raise_for_status()
payload = r.json()
df = pd.json_normalize(payload["Result"], sep="_")
df.to_parquet("ucdp_ged_26_1_page1.parquet", index=False)
print(len(df), "events of", payload["TotalCount"], "total", payload["TotalPages"], "pages")
```
Not run: it needs a free API key.

## Limits
- Rate limit: 5,000 requests per day; errors count.
- Large resources require paging; follow TotalPages or NextPageUrl.
- A page number far outside the result set can return a server error instead of an empty page.

## Quirks
- Every request must specify a dataset version, and a versioned URL is intended to remain reproducible.
- StartDate and EndDate filter date_end rather than a generic event timestamp.
- Invalid filter names are ignored, while invalid filter values return an empty result set.

## Terms and attribution
- UCDP datasets are licensed CC BY 4.0.
- Cite the relevant publications listed for the dataset and version used.
- Terms page: https://ucdp.uu.se/downloads/

## Sources
- https://ucdp.uu.se/apidocs/: "the API is free of charge"
- https://ucdp.uu.se/apidocs/: "5,000 requests per day"
- https://ucdp.uu.se/downloads/: "All datasets are free of charge and licensed under CC BY 4.0"
- https://ucdp.uu.se/downloads/: "published at a monthly release cycle"

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.