OmekaAPIClient.get_resources[source]OmekaAPIClient.get_resources(**`resource_type`**, **\\*\\*`kwargs`**)\n",
+ "\n",
+ "Get a list of resources matching the supplied parameters.\n",
+ "This will return the first page of matching results. To retrieve additional pages, \n",
+ "you can supply the `page` parameter to move through the full result set.\n",
+ "\n",
+ "Parameters:\n",
+ "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
+ "* there are many additional parameters you can supply as kwargs, see the Omeka documention\n",
+ "\n",
+ "Returns a dict with the following values:\n",
+ "* `total_results` - number of matching resources\n",
+ "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_resource_by_id[source]OmekaAPIClient.get_resource_by_id(**`resource_id`**, **`resource_type`**=*`'items'`*)\n",
+ "\n",
+ "Get a resource from its Omeka id.\n",
+ "\n",
+ "Parameters:\n",
+ "* `resource_id` - numeric identifier used by Omeka for this resource\n",
+ "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
+ "\n",
+ "Returns\n",
+ "* a dict containing a JSON-LD formatted representation of the resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_template_by_label[source]OmekaAPIClient.get_template_by_label(**`label`**)\n",
+ "\n",
+ "Get a resource template from its Omeka label.\n",
+ "\n",
+ "Parameters:\n",
+ "* `label` - the name of the resource template in Omeka (eg. 'NewspaperArticle')\n",
+ "\n",
+ "Returns:\n",
+ "* dict containing representation of the template"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_resource_by_term[source]OmekaAPIClient.get_resource_by_term(**`term`**, **`resource_type`**=*`'properties'`*)\n",
+ "\n",
+ "Get the resource (property or class) associated with the suppied term.\n",
+ "\n",
+ "Parameters:\n",
+ "* `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
+ "\n",
+ "Returns:\n",
+ "* dict containing representation of the resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_resource_from_vocab[source]OmekaAPIClient.get_resource_from_vocab(**`local_name`**, **`vocabulary_namespace_uri`**=*`'http://schema.org/'`*, **`resource_type`**=*`'properties'`*)\n",
+ "\n",
+ "Get the resource (property or class) associated with the suppied vocabulary and label.\n",
+ "\n",
+ "Parameters:\n",
+ "* `local_name` - label of the property or class\n",
+ "* `vocabulary_namespace_uri` - URI defining the vocab\n",
+ "\n",
+ "Returns:\n",
+ "* dict containing representation of the resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_property_id[source]OmekaAPIClient.get_property_id(**`term`**)\n",
+ "\n",
+ "Get the numeric identifier associated with the supplied property term.\n",
+ "\n",
+ "Parameters:\n",
+ "* `term` - property label qualified with vocabulary prefix (eg: 'schema:name')\n",
+ "\n",
+ "Returns:\n",
+ "* numeric identifier"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.filter_items_by_property[source]OmekaAPIClient.filter_items_by_property(**`filter_property`**=*`'schema:name'`*, **`filter_value`**=*`''`*, **`filter_type`**=*`'eq'`*, **`page`**=*`1`*, **\\*\\*`extra_filters`**)\n",
+ "\n",
+ "Filter the list of items by searching for a value in a particular property.\n",
+ "Additional filters can also limit to items associated with particular templates, classes, or item sets.\n",
+ "\n",
+ "Parameters:\n",
+ "* `filter_property` - property term (eg: 'schema:name')\n",
+ "* `filter_value` - the value you want to find\n",
+ "* `filter_type` - how `filter_value` should be compared to the stored values (eg: 'eq')\n",
+ "* `page` - number of results page\n",
+ "\n",
+ "Additional parameters:\n",
+ "* `resource_template_id` - numeric identifier\n",
+ "* `resource_class_id` - numeric identifier\n",
+ "* `item_set_id` - numeric identifier\n",
+ "* `is_public` - boolean, True or False\n",
+ "\n",
+ "Returns a dict with the following values:\n",
+ "* `total_results` - number of matching resources\n",
+ "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.search_items[source]OmekaAPIClient.search_items(**`query`**, **`search_type`**=*`'fulltext_search'`*, **`page`**=*`1`*, **\\*\\*`extra_filters`**)\n",
+ "\n",
+ "Search for matching items.\n",
+ "Two search types are available:\n",
+ "* 'search` - looks for an exact match of the query in a property value\n",
+ "* 'fulltext_search` - looks for the occurance of the query anywhere\n",
+ "\n",
+ "Parameters:\n",
+ "* `query` - the text you want to search for\n",
+ "* `search_type` - one of 'fulltext_search' or 'search'\n",
+ "* `page` - number of results page\n",
+ "\n",
+ "Additional parameters:\n",
+ "* `resource_template_id` - numeric identifier\n",
+ "* `resource_class_id` - numeric identifier\n",
+ "* `item_set_id` - numeric identifier\n",
+ "* `is_public` - boolean, True or False\n",
+ "\n",
+ "Returns a dict with the following values:\n",
+ "* `total_results` - number of matching resources\n",
+ "* `results` - a list of dicts, each containing a JSON-LD formatted representation of a resource"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.prepare_item_payload[source]OmekaAPIClient.prepare_item_payload(**`terms`**)\n",
+ "\n",
+ "Prepare an item payload, ready for upload.\n",
+ "\n",
+ "Parameters:\n",
+ "* `terms`: a dict of terms, values, and (optionally) data types\n",
+ "\n",
+ "Returns:\n",
+ "* the payload dict"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.prepare_item_payload_using_template[source]OmekaAPIClient.prepare_item_payload_using_template(**`terms`**, **`template_id`**)\n",
+ "\n",
+ "Prepare an item payload, checking the supplied terms and values against the specified template.\n",
+ "Note:\n",
+ "* terms that are not in the template will generate a warning and be dropped from the payload\n",
+ "* data types that don't match the template definitions will generate a warning and the term will be dropped from the payload\n",
+ "* if no data type is supplied, a type that conforms with the template definition will be used\n",
+ "\n",
+ "Parameters:\n",
+ "* `terms`: a dict of terms, values, and (optionally) data types\n",
+ "* `template_id`: Omeka's internal numeric identifier for the template\n",
+ "\n",
+ "Returns:\n",
+ "* the payload dict"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.add_media_to_payload[source]OmekaAPIClient.add_media_to_payload(**`payload`**, **`media_files`**)\n",
+ "\n",
+ "Add media files to the item payload.\n",
+ "\n",
+ "Parameters:\n",
+ "* `payload` - the payload dict to be modified\n",
+ "* `media_files` - media files to be uploaded\n",
+ "\n",
+ "The value of `media_files` can be either:\n",
+ "* a list of paths to the image/media files (filename is used as title)\n",
+ "* a list of dicts, each containing `title`, and `path` values\n",
+ "\n",
+ "Returns: \n",
+ "* the modified payload dict"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.add_item[source]OmekaAPIClient.add_item(**`payload`**, **`media_files`**=*`None`*, **`template_id`**=*`None`*, **`class_id`**=*`None`*, **`item_set_id`**=*`None`*)\n",
+ "\n",
+ "Create a new item from the supplied payload, optionally uploading attached media files.\n",
+ "\n",
+ "Parameters:\n",
+ "* `payload` - a dict generated by `prepare_item_payload()` or `prepare_item_payload_using_template()`\n",
+ "* `media_files` - a list of paths pointing to media files, or a list of dicts with `path` and `title` values\n",
+ "* `template_id` - internal Omeka identifier of a resource template you want to attach to this item\n",
+ "* `class_id` - internal Omeka identifier of a resource class you want to attach to this item\n",
+ "* `item_set_id` - internal Omeka identifier for an item set you want to add this item to\n",
+ "\n",
+ "Returns:\n",
+ "* a dict providing the JSON-LD representation of the new item from Omeka"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.format_resource_id[source]OmekaAPIClient.format_resource_id(**`resource_id`**, **`resource_type`**)\n",
+ "\n",
+ "Generate a formatted id for the resource with the specified Omeka id number and resource type.\n",
+ "\n",
+ "Parameters:\n",
+ "* `resource_id` - numeric identifier used by Omeka for this resource\n",
+ "* `resource_type` - one of Omeka's resource types, eg: 'items', 'properties'\n",
+ "\n",
+ "Returns:\n",
+ "* a dict with values for '@id' and 'o:id'"
+ ],
+ "text/plain": [
+ "OmekaAPIClient.prepare_property_value[source]OmekaAPIClient.prepare_property_value(**`value`**, **`property_id`**)\n",
+ "\n",
+ "Formats a property value according to its datatype as expected by Omeka. \n",
+ "The formatted value can be used in a payload to create a new item.\n",
+ "\n",
+ "Parameters:\n",
+ "* `value` - a dict containing a `value` and (optionally) a `type`\n",
+ "* `property_id` - the numeric identifier of the property\n",
+ "\n",
+ "Note that is no `type` is supplied, 'literal' will be used by default.\n",
+ "\n",
+ "Returns:\n",
+ "* a dict with values for `property_id`, `type`, and either `@id` or `@value`."
+ ],
+ "text/plain": [
+ "OmekaAPIClient.get_template_properties[source]OmekaAPIClient.get_template_properties(**`template_id`**)\n",
+ "\n",
+ "List properties used by the specified template.\n",
+ "\n",
+ "The resource template objects returned by the API don't include property terms.\n",
+ "This function gets the additional details, and organises the properties in a dictionary, \n",
+ "organised by term. This makes it easy to check if a particular term is used by a template.\n",
+ "\n",
+ "Parameters:\n",
+ "* `template_id` - numeric identifier for a template\n",
+ "\n",
+ "Returns:\n",
+ "* a dict organised by property terms, with values for `property_id` and `type`"
+ ],
+ "text/plain": [
+ "To initialise the OmekaAPIClient you need to provide the base url of your Omeka instance's API.
omeka = OmekaAPIClient('http://timsherratt.org/collections/api')
+This will let you access details of all public resources provided by your Omeka instance. To access private resources, or create new resources, you'll have to authenticate your API requests by provide a key_identity and key_credential. See Adding items for an example.
You can find a full list of Omeka's resources in the API documentation. You're most likely to be interested in 'items', but accessing 'properties' and 'resource_templates' can be useful when you're creating new resources.
+You should be able to use get_resources with any of the resource types, though some of the parameters will be different.
data = omeka.get_resources('items')
+data['total_results']
+assert isinstance(data['total_results'], int)
+data = omeka.get_resources('resource_templates')
+first_template = data['results'][0]
+assert first_template['@type'] == 'o:ResourceTemplate'
+data = omeka.get_resources('items')
+random_item = random.choice(data['results'])
+item_id = random_item['o:id']
+
+# Get the same item using its id
+item_from_id = omeka.get_resource_by_id(item_id, 'items')
+
+# Check that they're the same
+assert random_item == item_from_id
+It can be difficult to remember all the available parameters and the differences between resource types, so I've created a number of more specialised methods that are really just wrappers around get_resources.
newspaper_template = omeka.get_template_by_label('Newspaper')
+
+assert newspaper_template['@type'] == 'o:ResourceTemplate'
+assert newspaper_template['o:label'] == 'Newspaper'
+template_from_list = random.choice(omeka.get_resources('resource_templates')['results'])
+label = template_from_list['o:label']
+
+# Get the template using label
+template_from_label = omeka.get_template_by_label(label)
+
+# Check they're both the same
+assert template_from_list == template_from_label
+prop = omeka.get_resource_by_term('schema:name')
+prop
+omeka.get_resource_from_vocab(
+ 'name',
+ vocabulary_namespace_uri='http://schema.org/',
+ resource_type='properties')
+omeka.get_property_id('schema:name')
+omeka.filter_items_by_property(search_property='schema:name', search_text='name1')
+data = omeka.search_items('Newcastle')
+item_from_list = random.choice(omeka.get_resources('items'))
+
+# Get the same item using its id
+item_from_id = omeka.get_resource_by_id(item_from_list['o:id'])
+
+# Check that they're the same
+assert item_from_list == item_from_id
+template_from_list = random.choice(omeka.get_resources('resource_templates'))
+template_from_label = omeka.get_resource_by_label(template_from_list['o:label'], 'resource_templates')
+assert template_from_list == template_from_label
+property_from_list = random.choice(omeka.get_resources('properties'))
+vocabulary = s.get(property_from_list['o:vocabulary']['@id']).json()
+vocab_namespace_uri = vocabulary['o:namespace_uri']
+property_id = omeka.get_rdf_resource_id(property_from_list['o:local_name'], vocabulary_namespace_uri=vocab_namespace_uri)
+
+assert property_from_list['@id'] == property_id['@id']
+assert property_from_list['o:id'] == property_id['o:id']
+item_from_list = random.choice(omeka.get_resources('items'))
+name = item_from_list['schema:name'][0]['@value']
+
+found_item = omeka.find_item(name, property_name='name', vocabulary_namespace_uri='http://schema.org/')
+print(found_item)
+assert item_from_list == found_item
+omeka_auth = OmekaAPIClient(
+ api_url='http://timsherratt.org/collections/api',
+ key_identity=os.getenv('KEY_IDENTITY'),
+ key_credential=os.getenv('KEY_CREDENTIAL')
+)
+test_item = {
+ 'dcterms:title': [
+ {
+ 'value': 'My first resource!'
+ }
+ ]
+}
+payload = omeka_auth.prepare_item(test_item)
+payload
+Each term in the payload should have values for property_id and type, and the property value should be included as either @id or @value depending on the data type.
first_property = list(payload.values())[0][0]
+assert 'property_id' in first_property
+assert 'type' in first_property
+assert '@value' in first_property or '@id' in first_property
+One of the powerful features of Omeka S is the ability to create resource templates that define a set of properties for a particular type of item. We can use templates to help create our payload, ensuring that the terms and data types we supply match those expected by the template. This is useful for identifying potential problems before we upload to Omeka, especially as Omeka will sometimes just fail silently.
+ +Once you've created a payload, you can add paths to any media files that you want to be attached to the item.
+ +omeka_auth.add_item(payload)
+response['o:id']
+id_url = omeka.format_resource_id(5, 'resource_templates')
+
+assert id_url == {
+ '@id': 'http://timsherratt.org/collections/api/resource_templates/5',
+ 'o:id': 5
+}
+media_files = ['images/image1.png', 'images/image2.png']
+item = omeka_auth.prepare_item_using_template(test_item, 5)
+print(item)
+omeka_auth.add_item(item, template_id=5, media_files=media_files)
+In the example below I'm going to manually step through the process of adding a new item to Omeka using the API in order to demonstrate the methods available. But of course the point of using the API is to automate such processes -- joining together the individual steps so they can be embedded into your own systems or workflows.
+Let's suppose we want to add this newspaper article in Trove to our Omeka instance. To take best advantage of Omeka's linked data infrastructure, we'll actually create two resources -- one for the article, and one for the newspaper it was published in.
+I've already created templates labelled 'Newspaper' and 'Newspaper article'.
+Let's start with the newspaper. First we need to find out the numeric identifier Omeka is using for the Newspaper template. We can use OmekaAPIClient.get_template_by_label to find out.
omeka_auth = OmekaAPIClient(
+ api_url='http://timsherratt.org/collections/api',
+ key_identity=os.getenv('KEY_IDENTITY'),
+ key_credential=os.getenv('KEY_CREDENTIAL')
+)
+
+newspaper_template_id = omeka_auth.get_template_by_label('Newspaper')['o:id']
+newspaper_template_id
+For convenience, we can get a summary of the properties used in the Newspaper template using OmekaAPIClient.get_template_properties. This is useful if we want to check which properties are in use, and what data types are expected.
omeka_auth.get_template_properties(newspaper_template_id)
+The first step in preparing our data for upload is to create a dictionary, using the required property terms as keys. In this case, we'll assign data about the newspaper to schema.name and schema.url.
newspaper = {
+ 'schema.name': [
+ {
+ 'type': 'literal',
+ 'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'
+ }
+ ],
+ 'schema:url': [
+ {
+ 'type': 'literal',
+ 'value': 'http://nla.gov.au/nla.news-title806'
+ }
+ ]
+}
+Now we can use this data to create a payload for upload to Omeka. OmekaAPIClient.prepare_item_payload_using_template will check our data against the Newspaper template and build the payload.
payload = omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id)
+Whoops! It seems we have some problems with our data file! First of all we've used a full stop, rather than a colon in schema:name. Second, we've said the data type of schema:url is 'literal', but if we check the template properties we'll see it' should be 'uri'. Let's make these changes.
newspaper = {
+ 'schema:name': [
+ {
+ 'type': 'literal',
+ 'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'
+ }
+ ],
+ 'schema:url': [
+ {
+ 'type': 'uri',
+ 'value': 'http://nla.gov.au/nla.news-title806'
+ }
+ ]
+}
+payload = omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id)
+That seems better! Now we can examine the payload.
+ +payload
+Notice how the values have been reformatted? They should now be ready to upload to Omeka using OmekaAPIClient.add_item. We'll supply both the payload and the newspaper template id.
newspaper_item = omeka_auth.add_item(payload, template_id=newspaper_template_id)
+We can check the contents of newspaper_item to make sure it's been added succesfully.
newspaper_item
+Great! Now what about the article? Again let's start by having a look at the 'Newspaper article' template.
+ +article_template_id = omeka_auth.get_template_by_label('Newspaper article')['o:id']
+omeka_auth.get_template_properties(article_template_id)
+This time we'll build our data file in stages.
+ +article = {}
+
+# Add value for schema:name
+article['schema:name'] = ["MR WRAGGE'S PREDICTION. RENEWAL OF CYCLONE FORETOLD."]
+You'll notice that this time I've only included the value of the property, not the data type. This is because OmekaAPIClient.prepare_item_payload_using_template will insert default data types if they're not specified. The basic rules it uses if you don't supply a data type are:
In the case above, the 'literal' data type will be assigned to the schema:name value.
To create a link between the article and the newspaper it was published in, we can use schema.isPartOf. If we look in the list of template properties we see that this property expects a data type of 'resource:item'.
'schema:isPartOf': {'property_id': 736, 'type': ['resource:item']}The 'resource:item' data type means that the value will be an identifier pointing to another Omeka item. So we include the identifier of the newly-created newspaper record. Once again, the data type will be automatically added when we generate the payload.
+ +article['schema:isPartOf'] = [newspaper_item['o:id']]
+Next we'll add the publication date. To recognise dates as specific data types, you need to install the Numeric Data Types module. Once that's done, you can set the 'numeric:timestamp' data type as the default for any date fields in your template. In the list of properties from the newspaper article template, you can see:
+ +'schema:datePublished': {'property_id': 928, 'type': ['numeric:timestamp']}The date value itself is supplied in a standard ISO format -- 'YYYY-MM-DD'.
+ +article['schema:datePublished'] = ['1918-03-14']
+Finally we'll add a link to the article. Once again the template includes a default data type.
+ +'schema:url': {'property_id': 393, 'type': ['uri']}So we can just include the value.
+ +article['schema:url'] = ['http://nla.gov.au/nla.news-article226799674']
+Now that we've assembled the article metadata, we can generate a payload.
+ +article_payload = omeka_auth.prepare_item_payload_using_template(article, article_template_id)
+As you can see below, the default data types have been inserted into the payload, and some additional fields have been added to define the link to the newspaper item.
+ +article_payload
+We could now go ahead and upload the payload to Omeka, but what if we want to include media files? In this case I have a JPG image of the article I want to attach. All you need to do is supply a list of paths pointing to media files using the media_files parameter. The list can just include the paths as strings, in which case the file name will be used as the media object's title. Alternatively, you can supply a list of dicts, each containing a path and title value.
media_files = ['media/nla.news-article226799674-24144902.jpg']
+
+# Include the media files when we upload the payload
+article_item = omeka_auth.add_item(article_payload, media_files=media_files, template_id=article_template_id)
+When we look at the uploaded item, we'll see that the media files have been processed and added to the record.
+ +article_item
+This file will become your README and also the index of your documentation.
+ +pip install your_project_name
Fill me in please! Don't forget code examples:
+ +1+1
+