Identifiers

An identifier is the value that addresses one resource in the Wikimedia Enterprise API. It is the most reused parameter in the API: almost every path ends in /{identifier}, and the format it expects depends on what you are addressing. A snapshot identifier looks nothing like a language identifier, for instance. This page is the reference for all of them.

Identifier by resource

Every row is an endpoint that takes an {identifier} path parameter.

How a snapshot identifier is built

Snapshot bundles, Structured Contents snapshots, and hourly batch files all share one recipe:

<language><project_code>_namespace_<number>

The language and project code together are the project identifier, also found in the identifier field of the Projects Available endpoint, e.g. eswikivoyage. It's safer to read the identifier value rather than assembling the string yourself. Language codes do not all follow one standard and can be two or three characters (e.g. chy for Cheyenne), and not every project has a predictable project code (e.g. Wikidata's project identifier is wikidatawiki).

Chunk identifiers extend the same value with _chunk_<number>, so dewiki_namespace_0 chunks are dewiki_namespace_0_chunk_0, dewiki_namespace_0_chunk_1, and so on. Take them from the chunks array of a Snapshot Info response. The number of chunks varies per snapshot bundle.

Wikidata is the exception to the recipe. Its snapshots and hourly batches are addressed by items or properties, the bundles report wikidata_items and wikidata_properties as their identifier, and their chunks are wikidata_items_chunk_0 and up. See Wikidata snapshots.

Wikimedia Enterprise serves namespaces 0 (Main), 6 (File), 10 (Template), and 14 (Category). See Namespaces for info on what data each Namespace contains.

Structured Contents is a subset

Structured Contents snapshots use the same identifier format, but are restricted to a smaller subset of projects that have been thoroughly tested and released in beta. Structured Contents snapshots currently cover the following projects: enwiki_namespace_0, dewiki_namespace_0, frwiki_namespace_0, eswiki_namespace_0, ptwiki_namespace_0, itwiki_namespace_0, nlwiki_namespace_0, cywiki_namespace_0, and idwiki_namespace_0.

How to find a valid identifier

Discover identifiers by:

1. Requesting metadata endpoints Snapshots Available returns every available snapshot bundle, Hourly Batch Files Available does the same per date and hour, and Snapshot Info lists a bundle's chunk identifiers. Wikidata Snapshot Info lists identifiers and metadata for the two Wikidata bundles.
2. Building identifiers from multiple metadata fields Call the utility endpoints in order (codes, languages, projects, namespaces) to confirm each part before you compose it. That reference data changes rarely, so cache it instead of requesting it on every run.

The recommended way to discover project snapshot identifiers is to request the Snapshots Available endpoint using the fields request body parameter to pass the identifier field. See the example request below.

curl --location 'https://api.enterprise.wikimedia.com/v2/snapshots' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{ "fields": ["identifier"] }'

[
  { "identifier": "abwiki_namespace_0" },
  { "identifier": "abwiki_namespace_6" },
  { "identifier": "abwiki_namespace_10" }
]

A request with a well-formed but nonexistent identifier returns 404, not a validation error, so a typo and an unavailable bundle look the same from the outside.

Article names

The On-demand API addresses articles by name, which aren't unique identifiers: /v2/articles/{name} and /v2/structured-contents/{name} both take the article title as it appears on the wiki. Names are case sensitive, and spaces are passed as underscores (Josephine_Baker) or percent-encoded (Josephine%20Baker).

A name is not unique across Wikimedia projects. An unfiltered lookup returns a match from every project that has an article by that name, so filter on is_part_of.identifier for a project or in_language.identifier for a language to pin the result to one wiki. See Fields, Filters, and Limit for the syntax.

Identifiers inside a payload

Response bodies use identifier as a field name too, at several levels of the same object. They are not interchangeable with the path identifiers above.

An article identifier is a page ID, which is not the same as the article name. Page IDs can't be used as input to the On-demand API. The version.identifier is a revision ID that changes with every edit. Find definitions for all of the identifiers above in the article model.

See also

• Metadata - the utility endpoints that supply every part of an identifier.
• Snapshot API - download entire projects as compressed NDJSON tarballs.
• Realtime API - hourly batches reuse the snapshot identifier format.
• On-demand API - article lookups by name.
• Data Model - how the objects in a payload fit together.