InternetArchive

public convenience init()

public init(urlGenerator: InternetArchiveURLGeneratorProtocol, urlSession: URLSession)

Search the Internet Archive

public func search(query: InternetArchiveURLStringProtocol,
                   page: Int,
                   rows: Int,
                   fields: [String]? = nil,
                   sortFields: [InternetArchiveURLQueryItemProtocol]? = nil,
                   completion: @escaping (InternetArchive.SearchResponse?, Error?) -> Void)

Fetch a single item from the Internet Archive

public func itemDetail(identifier: String, completion: @escaping (InternetArchive.Item?, Error?) -> Void)

public func generateItemImageUrl(itemIdentifier: String) -> URL?

public func generateMetadataUrl(identifier: String) -> URL?

public func generateDownloadUrl(itemIdentifier: String, fileName: String) -> URL?

Errors that may be returned by the InternetArchive class

See more

public enum InternetArchiveError : Error

The main structure for defining search queries.

It can be created with key: value pairs like ["collection": "etree"] or an array of query clauses. The output is a URL string, such as "collection:(etree) AND -title:(foo)" in asURLString.

Basic Usage:

// generate a query for items in the etree collection
let query = InternetArchive.Query(clauses: ["collection": "etree"])

// generate a query for items not in the etree collection
let query = InternetArchive.Query(clauses: ["-collection": "etree"])

// generate a query for any field with a value of etree
let query = InternetArchive.Query(clauses: ["": "etree"])

Advanced Usage:

let clause1 = InternetArchive.QueryClause(field: "title", value: "String Cheese", booleanOperator: .and)
let clause2 = InternetArchive.QueryClause(field: "foo", value: "bar", booleanOperator: .not)
let dateInterval = DateInterval(start: startDate, end: endDate)
let dateRangeClause = InternetArchive.QueryDateRange(queryField: "date", dateRange: dateInterval)

let query = InternetArchive.Query(clauses: [clause1, clause2, dateRangeClause, sortField])

See more

public struct Query : InternetArchiveURLStringProtocol

A query clause for use in generating a Query.

This is comprised of a field, value, and booleanOperator. It will generate a search clause like collection:(etree).

field can be empty to search any field

Example Usage:

let clause1 = InternetArchive.QueryClause(field: "foo", value: "bar", booleanOperator: .and)
let clause2 = InternetArchive.QueryClause(field: "bar", value: "foo", booleanOperator: .not)

See more

public struct QueryClause : InternetArchiveQueryClauseProtocol

A query clause for use in generating a date range query.

This is comprised of a field and dateRange. It will return a query like date:[2018-01-01T07:23:12Z TO 2018-04-01T17:53:34Z]

Example Usage:

let startDate = Date(timeIntervalSince1970: 0)
let endDate = Date()
let dateInterval = DateInterval(start: startDate, end: endDate)
let dateRangeClause = InternetArchive.QueryDateRange(queryField: "date", dateRange: dateInterval)

See more

public struct QueryDateRange : InternetArchiveQueryClauseProtocol

See more

public enum BooleanOperator : String

A query item for use in generating a sort field.

This is comprised of a field and direction. direction is either .asc or .desc

Example Usage:

let sortField = InternetArchive.SortField(field: "date", direction: .asc)

See more

public struct SortField : InternetArchiveURLQueryItemProtocol

See more

public enum SortDirection : String

The top-level response from a search request

See more

public struct SearchResponse : Decodable

The response headers from a search request

See more

public struct ResponseHeader : Decodable

The response from a search request, containing the search results (docs)

See more

public struct Response : Decodable

The response parameters from a search request

This contains the query information that you sent in the search request.

See more

public struct ResponseParams : Decodable

See more

public class URLGenerator : InternetArchiveURLGeneratorProtocol

An abstraction for Internet Archive-style metadata fields.

Internet Archive metadata fields can be stored as strings or an array of strings. Typically we want to use these fields in a native types (Int, Double, Date, URL, etc). The ModelField struct does a few things to make handling these values more convenient:

• Provides a generic interface to any native type that is parsable from a string
• Converts the fields from strings to their native type
• Normalizes the response to an array of objects
• Provides a convenience value accessor to get the first value of the array since most fields are single values

Native types are wrapped in ModelFieldProtocol objects like IAInt and IADate to handle the string to native conversion.

Example Usage:

struct Foo: Decodable {
  let foo: ModelField<IAInt>
  let bar: ModelField<IAString>
}
let json: String = "{ \"foo\": \"3\", \"bar\": [\"boop\", \"bop\"] }"
let data = json.data(using: .utf8)!
let results: Foo = try! JSONDecoder().decode(Foo.self, from: data)
results.foo.values => [3]
results.foo.value => 3
results.bar.values => ["boop", "bop"]
results.bar.value => "boop"

See more

public struct ModelField<T> : Decodable where T : ModelFieldProtocol

Internet Archive Int field

Example Usage

let intField = IAInt(fromString: "3")
intField.value => 3

See more

public class IAInt : ModelFieldProtocol

Internet Archive String field

Example Usage

let stringField = IAInt(fromString: "Foo")
stringField.value => "Foo"

See more

public class IAString : ModelFieldProtocol

Internet Archive Double field

Example Usage

let doubleField = IADouble(fromString: "13.54")
doubleField.value => 13.54

See more

public class IADouble : ModelFieldProtocol

Internet Archive Bool field

Example Usage

let boolField = IABool(fromString: "true")
boolField.value => true

See more

public class IABool : ModelFieldProtocol

Internet Archive URL field

Example Usage

let urlField = IAURL(fromString: "https://archive.org")
urlField.value => URL "https://archive.org"

See more

public class IAURL : ModelFieldProtocol

Internet Archive Date field

Parses the following formats:

ISO8601 (2018-11-15T08:23:41Z, 2018-11-15T08:23:41-07:00, etc)

Year (2018)

Year Month (2018-09)

Approximate Year ([2018])

Circa Year (c.a. 2018)

Note: The approximate and circa formats do not have a representation that they’re approximate, since the Date type has no way of representing it.

Example Usage

let dateField = IADate(fromString: "2018-11-15T08:23:41Z")
dateField.value => Date "2018-11-15T08:23:41Z"

See more

public class IADate : ModelFieldProtocol

Internet Archive TimeInterval field. Used for fields like length of an audio file.

Parses the following formats:

• Seconds.Milliseconds (323.4)
• Duration (5:23.4)

Example Usage

let timeIntervalField1 = IATimeInterval(fromString: "12:37.4")
timeIntervalField1.value => TimeInterval 757.4

let timeIntervalField2 = IATimeInterval(fromString: "526.7")
timeIntervalField2.value => TimeInterval 526.7

See more

public class IATimeInterval : ModelFieldProtocol

An Internet Archive File

This will be returned in the files property from an InternetArchive().itemDetail() request.

Note: The properties are all type ModelField<T> except name, which is a String. This means you need to access all values by their .value or .values properties, except for identifier, which you can access directly.

Some Background: All other fields can be a string or array of strings so we can’t access them directly. See the ModelField class for a more thorough explanation.

For example:

let file = File(...some file...)
file.name = "SCIRedRocksConcert.track1.mp3" // `name` is always a String, it's like the primary key for the file
file.length.value = TimeInterval object // we want to cast all other fields to their native type

See the Internet Archive’s Python API Reference for a description of the properties.

Note: This is not an exhaustive list of properties. If you need some that are missing, please open a pull request.

See more

public struct File : Decodable

An Internet Archive Item, containing ItemMetadata, an array of File objects, and additional properties.

This will be returned from an InternetArchive().itemDetail() request.

See more

public struct Item : Decodable

Internet Archive Item Metadata

This will be returned from itemDetail() and search() requests.

Note: The properties are all type ModelField<T> except identifier, which is a String. This means you need to access all values by their .value or .values properties, except for identifier, which you can access directly.

Some Background: All other fields can be a string or array of strings so we can’t access them directly. See the ModelField class for a more thorough explanation.

For example:

let metadata = ItemMetadata(...some metadata...)
metadata.identifier = "SCIRedRocksConcert" // `identifier` is always a String
metadata.venue.value = "Red Rocks" // other fields can be a string or array of strings so you can't access directly

See the Internet Archive’s Python API Reference for a description of the properties.

Note: This is not an exhaustive list of metadata properties. If you need some that are missing, please open a pull request.

See more

public struct ItemMetadata : Decodable