# UNHCR — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access comprehensive humanitarian data on refugee situations, population statistics, and operational information across countries and regions managed by UNHCR. Search and retrieve detailed documents, partner organizations, and country-specific insights to support humanitarian planning and research.

**Category:** Government & Public Data | **Website:** [data.unhcr.org/](https://data.unhcr.org/) | **Docs:** [parse.bot/marketplace/f5f14622-dbe2-48ad-a995-1c9885dd119a/data-unhcr-org-api](https://parse.bot/marketplace/f5f14622-dbe2-48ad-a995-1c9885dd119a/data-unhcr-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_country_detail

Get details for a specific country by ISO3 code. Returns the ISO3 code and embedded data visualization widgets (Power BI dashboards, Datawrapper charts, and map iframes) found on the country page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `iso3` | string | Yes | Lowercase ISO 3166-1 alpha-3 country code, as returned by list_countries (e.g. 'afg', 'col', 'ukr'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_country_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iso3":"<string>"}'
```

### get_document_detail

Get metadata for a specific UNHCR document by its numeric ID. Returns publish date, upload date, document type, and language when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `document_id` | string | Yes | Numeric document ID, as returned by search_documents (e.g. '122173', '52289'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_document_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"<string>"}'
```

### get_partners

List partner organizations working with UNHCR. Returns deduplicated partner names, filtering out empty and placeholder entries.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_partners \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_region_detail

Get details for a specific UNHCR region by slug. Returns the slug and embedded data visualization widgets (Power BI dashboards, map iframes) found on the region page. Some regions may have no widgets.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Region slug identifier, as returned by list_regions. Accepted values: 'rbesa', 'rbap', 'rba', 'rbwca'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_region_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### get_situation_detail

Get details for a specific situation by slug. Returns the slug and embedded data visualization widgets (Power BI dashboards, Datawrapper charts, dataviz pages, and map iframes) found on the situation page. Some situations may have no widgets if their data is rendered purely server-side.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Situation slug identifier, as returned by list_situations (e.g. 'afghanistan', 'ukraine', 'sudansituation'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_situation_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### get_situation_population_data

Get structured population data for a situation by slug. Fetches population-related widget data from the situation page, including geographic coordinates, population group metadata, and time series data. Returns an empty array when no population API endpoints are found on the page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Situation slug identifier, as returned by list_situations (e.g. 'afghanistan', 'ukraine'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/get_situation_population_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

### list_countries

List all countries covered by the UNHCR Operational Data Portal. Returns country names and ISO 3166-1 alpha-3 codes. Deduplicates entries by ISO3 code.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/list_countries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_document_repositories

List UNHCR document repositories. Returns repository names, slugs, and URLs.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/list_document_repositories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_regions

List UNHCR regional bureaus. Returns region names and URL slugs. Deduplicates entries by slug.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/list_regions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_situations

List all active refugee/displacement situations tracked by UNHCR. Returns situation names and URL slugs. Deduplicates entries by slug.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/list_situations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_documents

Search for UNHCR documents and reports by keyword. Returns document IDs, titles, and URLs. Results appear sorted by relevance. Omitting the query returns recent documents. Supports manual pagination via the page parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | string | No | Page number for pagination (e.g. '2'). |
| `query` | string | No | Search keyword. Omitting returns recent documents. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-data-unhcr-org-api-f5f14622/search_documents \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<string>","query":"<string>"}'
```