State APIdiplomacy.state.gov ↗
Retrieve all National Museum of American Diplomacy encyclopedia entries — people, practices, and terms — with letter, keyword, and type filters in one response.
What is the State API?
The diplomacy.state.gov API exposes the full encyclopedia of the National Museum of American Diplomacy through a single endpoint, list_encyclopedia_entries, returning up to 50 pages of results in one concatenated response. Each entry carries 6 structured fields including a site post ID, title, type classification, type label, and first letter. Filters for entry type, starting letter, and free-text keyword let you narrow the result set before it arrives.
curl -X GET 'https://api.parse.bot/scraper/4e5d454d-126b-40be-afd3-66547cb0a385/list_encyclopedia_entries?keyword=zzqxjv' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace diplomacy-state-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: National Museum of American Diplomacy Encyclopedia API."""
from parse_apis.diplomacy_state_gov_api import DiplomacyEncyclopedia, EntryType, InputFormatInvalid
client = DiplomacyEncyclopedia()
# Browse all entries, capped to the first 5.
for entry in client.entries.list(limit=5):
print(entry.title, f"({entry.type_label})", "-", entry.description[:80])
# Filter by type: only "people" entries.
person = client.entries.list(entry_type=EntryType.PEOPLE, limit=1).first()
if person is not None:
print(f"First person: {person.title} [{person.letter}]")
if person.url is not None:
print(f" Detail page: {person.url}")
# Keyword search with error handling for bad filter input.
try:
for entry in client.entries.list(keyword="treaty", limit=10):
print(entry.id, entry.title)
except InputFormatInvalid as e:
print("Bad filter:", e.message)
print("exercised: entries.list (unfiltered / by type / by keyword)")
Returns every encyclopedia entry matching the optional filters in one response: the scraper walks all listing pages (10 entries per page, hard cap 50 pages) and concatenates them, so there is no caller-side pagination. Result grain is one row per encyclopedia entry, in the site's alphabetical order. Cost is one request per 10 entries (about 14 requests for the full unfiltered list of ~132 entries). Each entry carries its site id, title, type (people | practices | term), first letter, short description (may be empty on a few entries) and a detail page url, which is present only for People and Practices entries; Term entries have no detail page and return url null. `total` is the count the site reports for the filter, `count` is how many rows were returned, and `complete` is true when count reached total. Filters combine with AND. A keyword with no matches returns total 0 and an empty entries array. An unrecognized entry_type or a multi-character letter is rejected before any request.
| Param | Type | Description |
|---|---|---|
| letter | string | Single letter A-Z (case-insensitive); only entries whose title starts with that letter. Omitted = all letters. |
| keyword | string | Free-text keyword searched by the site across entry titles and bodies. Omitted = no keyword filter. |
| entry_type | string | Restrict to one entry type. Omitted = all types. |
{
"type": "object",
"fields": {
"count": "integer number of entries returned in this response",
"total": "integer count of matching entries reported by the site",
"entries": "array of entry objects: id (string site post id), title, type (people|practices|term), type_label (site display label), letter (uppercase first letter), description (short text, may be empty string), url (detail page link or null for Term entries)",
"filters": "object echoing the applied entry_type, letter and keyword (null when not applied)",
"complete": "boolean, true when count equals total",
"pages_fetched": "integer number of site listing pages walked"
},
"sample": {
"data": {
"count": 132,
"total": 132,
"entries": [
{
"id": "2624",
"url": null,
"type": "term",
"title": "Accession",
"letter": "A",
"type_label": "Term",
"description": "The procedure by which a nation becomes a party to an agreement already in force between other nations."
},
{
"id": "1404",
"url": "https://diplomacy.state.gov/encyclopedia/world-hunger/",
"type": "practices",
"title": "World Hunger",
"letter": "W",
"type_label": "Practices",
"description": "The Department of State believes that the most effective food security strategies come from those closest to the problems. In recent months, through the leadership of the…"
}
],
"filters": {
"letter": null,
"keyword": null,
"entry_type": null
},
"complete": true,
"pages_fetched": 14
},
"status": "success"
}
}About the State API
What the API Returns
The list_encyclopedia_entries endpoint returns every encyclopedia entry from the National Museum of American Diplomacy that matches the supplied filters. The response includes a count of entries returned, a total integer reported by the source, and an entries array where each object contains an id (the site's post ID), a title, a type slug (people, practices, or term), a type_label matching the site's own display text, and a letter indicating the first character of the title. A complete boolean tells you whether count equals total, so you can detect when the hard page cap was reached before all matching entries were collected.
Filtering Options
Three optional query parameters control what comes back. The letter parameter accepts any single letter A–Z (case-insensitive) and restricts results to entries whose title starts with that letter. The keyword parameter performs a free-text search across entry titles and bodies. The entry_type parameter restricts results to one of the three classification buckets: people, practices, or term. Any combination of these can be applied together; the filters object in the response echoes exactly which values were used (or null for each one that was omitted).
Pagination Behavior
The API handles multi-page traversal internally. The source presents entries in pages of 10; this endpoint walks up to 50 of those pages and concatenates all results before returning. The caller receives one flat entries array and a pages_fetched integer showing how many listing pages were consumed. There is no cursor or page parameter for the caller to manage.
The State API is a managed, monitored endpoint for diplomacy.state.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when diplomacy.state.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official diplomacy.state.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a searchable index of diplomatic terms and practices using the
keywordandentry_typefilters - Generate an A–Z glossary of American diplomacy concepts by iterating the
letterparameter from A to Z - Enumerate all 'people' entries to compile a reference list of historical diplomatic figures
- Cross-reference diplomacy encyclopedia entries with external historical databases using the
idfield as a stable key - Filter to 'practices' type entries to extract a structured list of diplomatic procedures and methodologies
- Monitor whether
completeis false to detect when result sets exceed the 50-page crawl limit for large queries
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does diplomacy.state.gov have an official developer API?+
What does the `type` field distinguish between entries?+
type slug that is one of three values: people (individuals), practices (diplomatic methods and procedures), or term (concepts and terminology). The type_label field contains the display text the site itself uses for that classification, which may differ slightly from the slug.Does the API return the full body text or article content for each encyclopedia entry?+
list_encyclopedia_entries endpoint returns listing-level data: id, title, type, type_label, and letter. Full article body content per entry is not included in the response. You can fork the API on Parse and revise it to add a detail endpoint that fetches the full text for a given entry ID.What happens when a filtered query matches more than 500 entries?+
complete field in the response will be false and count will be less than total. Applying the letter or entry_type filters to narrow the query is the practical way to stay within the cap.Can I retrieve entries sorted by a field other than first letter, such as by type or by date added?+
letter, keyword, and entry_type, but does not expose a sort parameter. The entries are returned in the order the source presents them. You can fork the API on Parse and revise it to add a sort parameter if a different ordering is needed.