Compare revisions

GET /core/v1/{project}/{language}/revision/{from}/compare/{to}

Returns data that lets you display a line-by-line comparison of two revisions. (See an example.) Only text-based wiki pages can be compared.

Examples

curl

# Compare revisions 847170467 and 851733941 to the Earth article on English Wikipedia
$ curl https://api.wikimedia.org/core/v1/wikipedia/en/revision/847170467/compare/851733941

Python

# Python 3
# Compare revisions 847170467 and 851733941 to the Earth article on English Wikipedia

import requests

from_revision = '847170467'
to_revision = '851733941'
url = 'https://api.wikimedia.org/core/v1/wikipedia/en/revision/' + from_revision + '/compare/' + to_revision

headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'User-Agent': 'YOUR_APP_NAME (YOUR_EMAIL_OR_CONTACT_PAGE)'
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

PHP

<?php
// Compare revisions 847170467 and 851733941 to the Earth article on English Wikipedia

$from = '847170467';
$to = '851733941';
$authorization = 'Authorization: Bearer YOUR_ACCESS_TOKEN';

$url = 'https://api.wikimedia.org/core/v1/wikipedia/en/revision/' . $from . '/compare/' . $to;

$ch = curl_init( $url );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $ch, CURLOPT_HTTPHEADER, array( $authorization ));
curl_setopt( $ch, CURLOPT_USERAGENT, 'YOUR_APP_NAME (YOUR_EMAIL_OR_CONTACT_PAGE)' );
$output = curl_exec( $ch );
curl_close( $ch );

echo( $output );
?>

JavaScript

// Compare revisions 847170467 and 851733941 to the Earth article on English Wikipedia

let url = 'https://api.wikimedia.org/core/v1/wikipedia/en/revision/847170467/compare/851733941';
let response = await fetch( url,
    {
        headers: {
            'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
            'Api-User-Agent': 'YOUR_APP_NAME (YOUR_EMAIL_OR_CONTACT_PAGE)'
        }
    }
);
response.json()
    .then(console.log).catch(console.error);

Parameters

project

required path

Project name. For example: wikipedia (encyclopedia articles), commons (images, audio, and video), wiktionary (dictionary entries). List all projects.
language

required path

Language code. For example: ar (Arabic), en (English), es (Spanish). List supported languages.
Note: The language parameter is prohibited for commons and other multilingual projects.
from

required path

Revision identifier to use as the base for comparison
to

required path

Revision identifier to compare to the base

Responses

200 Success: Revisions found
Example
{
  "from": {
    "id": 847170467,
    "slot_role": "main",
    "sections": [
      {
        "level": 2,
        "heading": "==Description==",
        "offset": 3006
      },
      {
        "level": 2,
        "heading": "==Taxonomy==",
        "offset": 4324
      },
      {
        "level": 3,
        "heading": "===Family placement===",
        "offset": 4643
      },
      {
        "level": 3,
        "heading": "===Species===",
        "offset": 9513
      },
      {
        "level": 2,
        "heading": "==Cultivation==",
        "offset": 12089
      },
      {
        "level": 2,
        "heading": "==Allergenic potential==",
        "offset": 15634
      },
      {
        "level": 2,
        "heading": "==References==",
        "offset": 15985
      },
      {
        "level": 2,
        "heading": "==External links==",
        "offset": 16018
      }
    ]
  },
  "to": {
    "id": 851733941,
    "slot_role": "main",
    "sections": [
      {
        "level": 2,
        "heading": "==Description==",
        "offset": 3006
      },
      {
        "level": 2,
        "heading": "==Taxonomy==",
        "offset": 4324
      },
      {
        "level": 3,
        "heading": "===Family placement===",
        "offset": 4643
      },
      {
        "level": 3,
        "heading": "===Species===",
        "offset": 9513
      },
      {
        "level": 2,
        "heading": "==Cultivation==",
        "offset": 12089
      },
      {
        "level": 2,
        "heading": "==Allergenic potential==",
        "offset": 16157
      },
      {
        "level": 2,
        "heading": "==References==",
        "offset": 16508
      },
      {
        "level": 2,
        "heading": "==External links==",
        "offset": 16541
      }
    ]
  },
  "diff": [
    {
      "type": 0,
      "lineNumber": 95,
      "text": "",
      "offset": {
        "from": 14692,
        "to": 14692
      }
    },
    {
      "type": 0,
      "lineNumber": 96,
      "text": "Though ''Neuranethes spodopterodes'' is invasive in the regions where it has emerged as a pest, it is not an exotic invader, but a [[Species translocation|translocated species]], having been imported inadvertently from its natural range in more northerly regions of the country. In its original range the moth is not of horticultural importance, being controlled by natural enemies that as yet have neither been identified nor imported along with the host plants. In contrast the ''Agapanthus'' borer is of considerable concern in the South West, and its voracity is so impressive that the species shows promise as a possible control for invasive ''Agapanthus praecox'' in countries like New Zealand.<ref>M.D. Picker and M. Krüger. Spread and Impacts of the Agapanthus Borer (Neuranethes spodopterodes (Hampson, 1908), comb. nov.), a Translocated Native Moth Species (Lepidoptera: Noctuidae). African Entomology 2013 21 (1), 172-176</ref>",
      "offset": {
        "from": 14693,
        "to": 14693
      }
    },
    {
      "type": 1,
      "lineNumber": 97,
      "text": "",
      "offset": {
        "from": null,
        "to": 15633
      }
    },
    {
      "type": 1,
      "lineNumber": 98,
      "text": "In 2016, a new species of [[Cecidomyiidae|gall midge]], ''[[Enigmadiplosis agapanthi]]'', was described damaging Agapanthus in the [[United Kingdom]].<ref>{{cite journal| last1 =Harris | first1 =KM | last2 =Salisbury |first2=A| last3=Jones |first3=H | title =''Enigmadiplosis agapanthi'', a new genus and species of gall midge (Diptera, Cecidomyiidae) damaging Agapanthus flowers in England. | journal =Cecidology | volume =31 | issue = | pages =17-20 | publisher =British Gall Society | location = | date =2016 }} </ref>",
      "offset": {
        "from": null,
        "to": 15634
      }
    },
    {
      "type": 0,
      "lineNumber": 99,
      "text": "",
      "offset": {
        "from": 15633,
        "to": 16156
      }
    },
    {
      "type": 0,
      "lineNumber": 100,
      "text": "==Allergenic potential==",
      "offset": {
        "from": 15634,
        "to": 16157
      }
    }
  ]
}
400 Error: Revision IDs are for different pages or for pages that can't be compared
Example
{
  "messageTranslations": {
    "en": "The specified revisions belong to different pages; refusing to compare them."
  },
  "httpCode": 400,
  "httpReason": "Bad Request"
}
404 Error: Revision not found
Example
{
  "messageTranslations": {
    "en": "The revision specified by the to parameter does not exist."
  },
  "httpCode": 404,
  "httpReason": "Not Found"
}

Response schema

from

required object

Information about the base revision used in the comparison
Properties
id

integer

Revision identifier
slot_role

string

Area of the page being compared, usually main
sections

array

Array of objects representing section headings
Properties
level

integer

Heading level, 1 through 4
heading

string

Text of the heading line, in wikitext
offset

integer

Location of the heading, in bytes from the beginning of the page
to

required object

Information about the revision being compared to the base revision
Properties
id

integer

Revision identifier
slot_role

string

Area of the page being compared, usually main
sections

array

Array of objects representing section headings
Properties
level

integer

Heading level, 1 through 4
heading

string

Text of the heading line, in wikitext
offset

integer

Location of the heading, in bytes from the beginning of the page
diff

required string

Each object in the diff array represents a line in a visual, line-by-line comparison between the two revisions.
Properties
type

integer

The type of change represented by the diff object, either:
  • 0: A line with the same content in both revisions, included to provide context when viewing the diff. The API returns up to two context lines around each change.
  • 1: A line included in the to revision but not in the from revision.
  • 2: A line included in the from revision but not in the to revision.
  • 3: A line containing text that differs between the two revisions. (For changes to paragraph location as well as content, see type 5.)
  • 4: When a paragraph's location differs between the two revisions, a type 4 object represents the location in the from revision.
  • 5: When a paragraph's location differs between the two revisions, a type 5 object represents the location in the to revision. This type can also include word-level differences between the two revisions.
lineNumber

integer

The line number of the change based on the to revision.
text

string

The text of the line, including content from both revisions. For a line containing text that differs between the two revisions, you can use highlightRanges to visually indicate added and removed text. For a line containing a new line, the API returns the text as "" (empty string).
highlightRanges

array

An array of objects that indicate where and in what style text should be highlighted to visually represent changes.

Each object includes:

Properties
start

integer

Where the highlighted text should start, in the number of bytes from the beginning of the line
length

integer

Length of the highlighted section, in bytes
type

integer

Type of highlight:
  • 0 indicates an addition.
  • 1 indicates a deletion.
moveInfo

object

Visual indicators to use when a paragraph's location differs between the two revisions. moveInfo objects occur in pairs within the diff.
Properties
id

string

Identifier of the paragraph described by the diff object
linkId

string

Identifier of the corresponding paragraph
  • For type 4 diff objects, linkId represents the location in the to revision.
  • For type 5 diff objects, linkId represents the location in the from revision.
linkDirection

integer

A visual indicator of the relationship between the two locations. You can use this property to display an arrow icon within the diff.
  • 0 indicates that the linkId paragraph is lower on the page than the id paragraph.
  • 1 indicates that the linkId paragraph is higher on the page than the id paragraph.
offset

object

Location of the line in bytes from the beginning of the page
Properties
from

integer

The first byte of the line in the from revision. A null value indicates that the line doesn't exist in the from revision.
to

integer

The first byte of the line in the to revision. A null value indicates that the line doesn't exist in the to revision.