General info@cupa.org.pk Media press@cupa.org.pk
Islamabad Washington, DC
CUPA logo Center for US-Pakistan Affairs Policy, Research & Action
For developers and researchers

Public API and embeddable charts

Read CUPA’s published research, trackers and data as JSON, or put one of our charts on your own site.

Technical manualAPI v1Revised

Getting started

The API is read-only, needs no key and answers GET requests from any website (CORS is open). It returns only what is published on this site. Start at the index, which lists every endpoint:

Shell
curl https://cupa.org.pk/api/v1

1.1 A first request

Shell
curl "https://cupa.org.pk/api/v1/publications?per_page=2"
JavaScript
const res = await fetch('https://cupa.org.pk/api/v1/publications?per_page=2');
const { data, meta, links } = await res.json();
console.log(meta.total, data.map((item) => item.title));

Endpoints

All paths are under https://cupa.org.pk/api/v1. Lists take page and per_page (default 20, at most 100); items are addressed by their slug, the last part of their address on this site.

PathWhat it returnsQuery parameters
/publications
/publications/{slug}		 Published research: briefs, papers, reports and commentary. kind, year, track, page, per_page
/issues
/issues/{slug}		 The Issue Map: issues with status, impact and location; one issue adds its updates and resources. status, region, type, impact, page, per_page
/trackers
/trackers/{slug}
/trackers/{slug}/entries		 Live trackers; one tracker adds its columns, entries and changelog (/trackers/{slug}/entries pages through entries). page, per_page
/long-arc
/long-arc/{slug}
/long-arc/eras		 The Long Arc: published events of US–Pakistan relations since 1947 (/long-arc/eras lists the eras); one event adds its key facts and sources. era, category, page, per_page
/datasets The data repository catalogue: datasets with licence, source and download links. kind, page, per_page
/congress The Congress tracker: bills, resolutions, hearings and Record sections that mention Pakistan. type, congress, chamber, status, keyword, q, page, per_page
/trade
/trade/monthly
/trade/annual
/trade/goods		 US–Pakistan goods trade (US Census Bureau): headline figures; /trade/monthly, /trade/annual and /trade/goods give the series. —
/people
/people/{slug}		 Public profiles of the Centre’s people (fields shown on their profile pages only). page, per_page
/search Site-wide search across published content. q (required), type, page

Fields are chosen one by one for each type; nothing from the editors’ portal (drafts, notes, review comments, sign-ups or contact details) is ever included. Full article texts stay on their pages: the API gives titles, summaries, facts, sources and the page address.

Try it

Send a real request to this site’s API and read the answer here. Only GET requests to /api/v1 on this site are sent; each one counts towards the rate limit like any other.

Responses

Every response is JSON in the same envelope. Lists carry paging details in meta and ready-made links to the next and previous pages (also sent as a Link header):

JSON
{
  "data": [ { "slug": "…", "title": "…", "url": "https://cupa.org.pk/…" } ],
  "meta": { "count": 20, "total": 57, "page": 1, "per_page": 20, "pages": 3,
            "next": "https://cupa.org.pk/api/v1/publications?page=2" },
  "links": { "self": "…", "next": "…", "prev": null, "docs": "https://cupa.org.pk/developers" }
}

4.1 Single items and errors

One item (/issues/{slug}, for example) comes back as an object in data. Errors use the HTTP status and a short message:

JSON
{ "error": { "status": 404, "message": "Not found." } }

4.2 Dates and methods

Dates are ISO 8601 (2026-03-14, or 2026-03-14T09:30:00Z with a time); event times carry their own UTC offset. Only GET, HEAD and OPTIONS are accepted; anything else gets 405 Method Not Allowed.

Caching and limits

  • Responses may be cached for five minutes (Cache-Control: public, max-age=300).
  • Each response has an ETag. Send it back in If-None-Match and you get an empty 304 Not Modified when nothing has changed.
  • Please keep to 120 requests a minute from one address. The headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset show where you are; past the limit you get 429 Too Many Requests with Retry-After.
  • For whole datasets, the downloads linked from each item (CSV and JSON) are usually quicker than paging through the API.

Embeddable charts

These charts can be placed on any website in an <iframe>. They need no script on your page, fit the width they are given and follow the reader’s light or dark setting; add ?theme=light or ?theme=dark to fix one. Each one links back to its page here. On the site, the Embed button under a chart gives you the code.

  • /embed/trade/monthly Monthly US–Pakistan goods trade
  • /embed/trade/annual Goods trade by year
  • /embed/congress/stages Bills and resolutions in the current Congress by stage
  • /embed/trackers/{slug} A live tracker’s latest entries
  • /embed/issues/{slug} An Issue Map issue: status, impact and latest updates

6.1 Previews

Fig. 6.1 Monthly US–Pakistan goods trade
HTML
<iframe src="https://cupa.org.pk/embed/trade/monthly"
        title="Monthly US–Pakistan goods trade" width="100%" height="520"
        style="border:0;max-width:100%" loading="lazy"></iframe>
Fig. 6.2 Goods trade by year
HTML
<iframe src="https://cupa.org.pk/embed/trade/annual"
        title="US–Pakistan goods trade by year" width="100%" height="520"
        style="border:0;max-width:100%" loading="lazy"></iframe>
Fig. 6.3 Bills and resolutions in the current Congress by stage
HTML
<iframe src="https://cupa.org.pk/embed/congress/stages"
        title="Pakistan in the US Congress: bills by stage" width="100%" height="470"
        style="border:0;max-width:100%" loading="lazy"></iframe>

Revision notes

Changes to the API and the embeds, newest first. Additions never break an existing integration; anything that would is announced here first.

  1. Rev. 1.2

    • Embeds take ?theme=light or ?theme=dark to fix their colours; without it they still follow the reader’s system setting.

  2. Rev. 1.1

    • New embed: /embed/data/{slug}, a chart of a dataset’s preview rows as set in the dataset page’s chart builder.

  3. Rev. 1.0

    • First release of /api/v1: publications, explainers, dispatches, issues, trackers, The Long Arc, events, datasets, Congress, trade, people and search.
    • Read-only JSON with open CORS, page-based paging, five-minute caching with ETags and a per-address rate limit.
    • Embeddable charts: monthly and annual goods trade, Congress bills by stage, a tracker’s latest entries and an Issue Map issue.

Licence and credit

The API follows our terms of use:

  • Data (our trackers, the datasets in the data repository and the figures we compile) is published under the Creative Commons Attribution 4.0 licence (CC BY 4.0), unless a dataset states another licence. Credit CUPA, link to the licence and say what you changed.
  • Official figures (trade statistics, congressional records) come from the public sources credited with them; please credit those sources too.
  • Texts (titles, summaries and excerpts of our publications and articles) remain © Center for US-Pakistan Affairs and their authors. You may quote short extracts with credit and a link to the original page.
  • Photographs belong to the people credited with them; ask them before reusing an image.

For anything else, such as republishing in full or heavier use of the API, write to info@cupa.org.pk.

End of manual.