The Wikipedia API is a complex beast. It takes some time (and willpower) to learn all of its idiosyncrasies.
With WikipediaKit, it’s easy to build apps that search and show Wikipedia content—without worrying about the raw API. Instead of exposing all options and endpoints, WikipediaKit provides comfortable access to the most interesting parts. It’s opinionated—but that’s the point!
The WikipediaKit framework is written in Swift 3, has no third-party dependencies, and runs on macOS, iOS, watchOS, and tvOS.
If this doesn’t convince you to build a shiny new reader app for Wikipedia yourself, have a look at V for Wiki, the award-winning app that WikipediaKit was created for.
You can use Carthage to install and update WikipediaKit.
Drag and drop the WikipediaKit.xcodeproj to your app project and add the WikipediaKit embedded framework in your app project’s build settings.
WikipediaKit is ready for the Swift Package Manager.
The Wikipedia class connects your app to Wikipedia’s API. You can search, get articles, and list nearby places by querying a freshly created Wikipedia instance…
let wikipedia = Wikipedia()…or by using the shared singleton instance:
let wikipedia = Wikipedia.sharedBefore doing anything else, make sure to add your email address:
WikipediaNetworking.appAuthorEmailForAPI = "appauthor@example.com"WikipediaKit will use this email address and your app’s bundle info to generate and send a User-Agent header. This will identify your app to Wikipedia’s servers with every API request, as required by the API guidelines.
The User-Agent header is printed to your Xcode console when you make the first API request. It’ll look something like this:
User-Agent: ExampleApp/1.0 (com.example.ExampleApp; appauthor@example.com) WikipediaKit/1.0
Please double-check that the User-Agent header is correct before shipping your app.
The return type of all Wikipedia methods is
a standard URLSessionTask:
let language = WikipediaLanguage("en")
let searchSessionTask = Wikipedia.shared.requestOptimizedSearchResults(language: language, term: "Soft rime") { (searchResults, error) in
// This code will be called asynchronously
// whenever the results have been downloaded.
// …
}A URLSessionTask can be cancelled like this:
searchSessionTask.cancel()See the URLSessionTask documentation for further reading.
A WikipediaLanguage has a language code, a localized name, an autonym, and sometimes a variant (e.g. zh-hans for Simplified Chinese and zh-hant for Traditional Chinese).
// French language, localized name for German, no variant
let l = WikipediaLanguage(code: "fr",
localizedName: "Französisch", // FR in DE
autonym: "Français") // FR in FRWikipediaKit comes with a list of most Wikipedia languages and their autonyms. This lets you initialize a WikipediaLanguage by passing only the language code. Please note that if you use this shorthand method, the localized names will be in English.
let language = WikipediaLanguage("fr")
// code: "fr", localizedName: "French", autonym: "Français"Search Wikipedia—e.g. for the term “Soft rime” in English—like this:
let language = WikipediaLanguage("en")
let _ = Wikipedia.shared.requestOptimizedSearchResults(language: language, term: "Soft rime") { (searchResults, error) in
guard error == nil else { return }
guard let searchResults = searchResults else { return }
for articlePreview in searchResults.results {
print(articlePreview.displayTitle)
}
}The searchResults are a WikipediaSearchResults object.
To load more search results for a query, simply start another search for the same language: and term:, passing the previous WikipediaSearchResults object as the existingSearchResults: parameter.
The default batch size is 15, but can be changed by passing a different number in the maxCount parameter.
There are two supported search methods (WikipediaSearchMethod) to search for articles on Wikipedia. You can pass them to requestSearchResults(method:language:term:).
.prefixsearches the article titles only.fullTextsearches the complete articles
For better search results quality, use requestOptimizedSearchResults(language:term:), which doesn’t take a method: parameter (see the example above). This will use the .prefix search and then fall back to the .fullText search whenever there are few or no results for a search term.
You can adjust the minimum number of results—before the fallback .fullText search is triggered—with the minCount: parameter.
The desired maximum pixel width of the WikipediaArticlePreview’s image URL can be adjusted in the optional imageWidth: parameter.
Searches are cached automatically until the app quits (see section on caching below).
WikipediaArticlePreview objects represent search result items. They’re similar to full articles, but contain only an excerpt of the article text.
The displayTitle and displayText can be formatted via your WikipediaFormattingDelegate.
Load the article about “Soft rime” in English like this:
let language = WikipediaLanguage("en")
// You need to pass in the maximum width
// in pixels for the returned thumbnail URL,
// for example the screen width:
let imageWidth = Int(self.view.frame.size.width * UIScreen.main.scale)
let _ = Wikipedia.shared.requestArticle(language: language, title: "Soft rime", imageWidth: imageWidth) { (article, error) in
guard error == nil else { return }
guard let article = article else { return }
print(article.displayTitle)
print(article.displayText)
}The displayTitle and displayText can be formatted via your WikipediaFormattingDelegate.
Wikipedia articles come with a table of contents, stored in a array of WikipediaTOCItem. The section titles can be formatted in your WikipediaFormattingDelegate.
To query other available languages for a given article, use the requestAvailableLanguages(for:) call on your Wikipediainstance, passing the existing article.
Articles are cached automatically until the app is restarted (see section on caching below).
This search mode returns geo-tagged articles around a specific location. Pass in a coordinate (latitude and longitude) around which to search:
let language = WikipediaLanguage("en")
let _ = Wikipedia.shared.requestNearbyResults(language: language, latitude: 52.4555592, longitude: 13.3175333) { (articlePreviews, resultsLanguage, error) in
guard error == nil else { return }
guard let articlePreviews = articlePreviews else { return }
for a in articlePreviews {
print(a.displayTitle)
if let coordinate = a.coordinate {
print(coordinate.latitude)
print(coordinate.longitude)
}
}
}The requestMostReadArticles(language:date:) query gets a list of the most popular articles for a specific date from Wikipedia’s official analytics.
let language = WikipediaLanguage("en")
let dayBeforeYesterday = Date(timeIntervalSinceNow: -60 * 60 * 48)
let _ = Wikipedia.shared.requestMostReadArticles(language: language, date: dayBeforeYesterday) { (articlePreviews, date, resultsLanguage, error) in
guard error == nil else { return }
guard let articlePreviews = articlePreviews else { return }
for a in articlePreviews {
print(a.displayTitle)
}
}Please note: The API will return a 404 error if there’s no data available for the requested date. The most recent data is usually from yesterday, so receiving a 404 for today is expected.
You may want to filter the results from the most read articles before displaying them in your app—they are potentially NSFW. That’s what the WikipediaBlacklistDelegate is for (see below).
To find out the URL for a given Wikipedia image at a specific size, use this call:
let language = WikipediaLanguage("en")
let url = "https://en.wikipedia.org/wiki/File:Raureif2.JPG"
let _ = Wikipedia.shared.(language: language, url: url, width: 1000) { (imageMetadata, error) in
guard error == nil else { return }
print(imageMetadata.url) // URL for 1000px width version
print(imageMetadata.description)
print(imageMetadata.license)
}Instead of the url: parameter, you can specify an image id:; in this case the id would be "File:Raureif2.JPG".
WikipediaKit comes with a few delegate protocols that help you track state, filter, and format.
WikipediaNetworking.sharedActivityIndicatorDelegate = MyActivityIndicatorDelegate.sharedSet a WikipediaNetworkingActivityDelegate to receive start() and stop() calls whenever a network operation starts and stops.
Wikipedia.sharedFormattingDelegate = MyFormattingDelegate.sharedThe WikipediaArticle and WikipediaArticlePreview classes have a displayTitle and a displayText property.
You can parse and reformat article texts, titles, and the table of contents in your WikipediaFormattingDelegate before it’s being cached.
class MyFormattingDelegate: WikipediaTextFormattingDelegate {
func format(context: WikipediaTextFormattingDelegateContext, rawText: String, title: String?, language: WikipediaLanguage, isHTML: Bool) -> String {
// Do something to rawText before returning…
return rawText
}
}Wikipedia.sharedBlacklistDelegate = MyBlacklistDelegate.sharedYou may wish to filter the most read articles before showing them as recommendations in your app. The WikipediaBlacklistDelegate protocol allows you to blacklist articles by title or description.
class MyBlacklistDelegate: WikipediaBlacklistDelegate {
func isBlacklistedForRecommendations(title: String,
language: WikipediaLanguage) -> Bool {
// Decide if title is blacklisted here…
return false
}
func containsBlacklistedWords(text: String, language: WikipediaLanguage) -> Bool {
// Decide if text contains blacklisted words…
return false
}
}Caching happens automatically (after processing and formatting) for search results and articles. WikipediaKit uses simple NSCache instances.
There’s also the automatic NSURLCache, controlled by the server’s cache headers. You can modify the cache duration headers to be included API response in Wikipedia.maxAgeInSeconds.
- Improve unit tests
- Pass request options in an array instead of function parameters
WikipediaKit was created by Frank Rausch (@frankrausch) for Raureif.
© 2017 Raureif GmbH / Frank Rausch
MIT License; please read the LICENSE file in this repository.
This project is not affiliated with the official Wikipedia projects or the Wikimedia Foundation.
Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.