Documentation menu

Fields, Filters, and Limit

Many Enterprise API endpoints accept filters, fields, and limit input parameters to customize the data returned in the API response. When using these options, it is best to send requests using the POST method and include the parameters in the JSON request body. This page explains the correct placement, syntax, and available options, with examples of how to pass fields, filters, and limit in your requests. The following snippet is an example of a typical JSON request body.

{
  "filters": [
    {
      "field": "is_part_of.identifier", "value": "enwiki"
    }
  ],
  "fields": ["name","url","is_part_of"],
  "limit": 1
}

Fields

Use fields if you only want a specific set of fields and values returned in the API response, such as article names or category URLs. Omitting the fields parameter will return all available fields in the API response.

The fields parameter takes an array of field names as input. Specify fields using dot notation. Any field in the API Response can be specified with fields: Objects such as version, arrays such as version.tags, or fields with a single value such as version.is_minor_edit. The article model in the API reference lists all the fields present in Enterprise API responses.

Example POST request using cURL to call the available Snapshots and only return the identifier info, date modified, and size of the snapshot:

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

Important:

By passing the fields parameter, you are specifying which fields to include exclusively. Only the field names you pass in the fields parameter will be returned by the API; fields not explicitly mentioned will not be returned in the API response.

Filters

Use filters when you need to retrieve data from a specific range of values, such as data from a specific project, language, or namespace. Omitting the filters parameter will return all possible articles that match the API request.

The filters parameter takes an array of objects as input. Every field specified in filters can only have one value associated with it. Only fields with a single value can be used in filters, e.g. "field":"version.is_minor_edit", "value":true. You cannot specify arrays (e.g. "version.tags"), or objects (e.g. "version"). Required fields can always be specified. Fields that are strings, integers, floats, and booleans can be used with filters. The article model in the API reference lists all the fields present in Enterprise API responses.

Example POST request using cURL to request all article data for "Marie Curie" in French:

curl --location 'https://api.enterprise.wikimedia.com/v2/articles/Marie_Curie' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{
  "filters": [
    {
      "field":"in_language.identifier", "value": "fr"
    }
  ]
}'

Important:

By passing the filters parameter, you are filtering in, or filtering down, to a specific subset of Wikimedia data. If you specify "field":"is_part_of.identifier", "value":"enwiki" as a filter, the API will only return data from English Wikipedia, and not from any other Wikimedia projects or languages.

Query form for GET requests

Every endpoint that takes fields and filters in a POST body also takes them as query parameters on a GET request, with the same meaning. Send one fields parameter per field, and one filters parameter per filter with the filter object as JSON, URL-encoded. Repeated filters parameters combine as AND. A comma-separated list in a single fields value is not supported, and a JSON array in a single filters value returns 422 Unprocessable Entity.

The request for Marie Curie in French above, sent as GET and asking for two fields:

curl -G 'https://api.enterprise.wikimedia.com/v2/articles/Marie_Curie' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-urlencode 'filters={"field":"in_language.identifier","value":"fr"}' \
--data-urlencode 'fields=name' \
--data-urlencode 'fields=version.identifier'

Limit

Set a limit to restrict the number of articles returned in an API response. The default value for limit is 3, and its maximum value is 10. Limit can only be used with On-demand endpoints.

Example of an On-demand API POST call that limits the number of articles returned for the Wikipedia article NATO (which has almost 200 different languages) to 1:

curl --location 'https://api.enterprise.wikimedia.com/v2/articles/NATO' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{
  "limit": 1
}'