api.html

---

title: Omeka S API client


keywords: fastai
sidebar: home_sidebar

summary: "Tools to interact with the Omeka S REST API"
description: "Tools to interact with the Omeka S REST API"
nb_path: "api.ipynb"
---
<!--

#################################################
### THIS FILE WAS AUTOGENERATED! DO NOT EDIT! ###
#################################################
# file to edit: api.ipynb
# command to build the docs after a change: nbdev_build_docs

-->

<div class="container" id="notebook-container">
        
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h2 id="OmekaAPIClient" class="doc_header"><code>class</code> <code>OmekaAPIClient</code><a href="https://github.com/wragge/omeka_s_tools/tree/master/omeka_s_tools/api.py#L13" class="source_link" style="float:right">[source]</a></h2><blockquote><p><code>OmekaAPIClient</code>(<strong><code>api_url</code></strong>, <strong><code>key_identity</code></strong>=<em><code>None</code></em>, <strong><code>key_credential</code></strong>=<em><code>None</code></em>, <strong><code>use_cache</code></strong>=<em><code>True</code></em>)</p>
</blockquote>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>First import the <a href="/omeka_s_tools/api.html#OmekaAPIClient"><code>OmekaAPIClient</code></a> class.</p>
<div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">omeka_s_tools.api</span> <span class="kn">import</span> <span class="n">OmekaAPIClient</span>
</pre></div>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>To initialise the <a href="/omeka_s_tools/api.html#OmekaAPIClient"><code>OmekaAPIClient</code></a> you need to provide the base url of your Omeka instance's API.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka</span> <span class="o">=</span> <span class="n">OmekaAPIClient</span><span class="p">(</span><span class="s1">&#39;http://timsherratt.org/collections/api&#39;</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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 <code>key_identity</code> and <code>key_credential</code>. See <a href="#Adding-items">Adding items</a> for an example.</p>

</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Getting-resources">Getting resources<a class="anchor-link" href="#Getting-resources"> </a></h2><p>You can find a <a href="https://omeka.org/s/docs/developer/api/#resources">full list of Omeka's resources</a> 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.</p>
<p>You should be able to use <code>get_resources</code> with any of the resource types, though some of the parameters will be different.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_resources" class="doc_header"><code>OmekaAPIClient.get_resources</code><a href="__main__.py#L63" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_resources</code>(<strong><code>resource_type</code></strong>, <strong>**<code>kwargs</code></strong>)</p>
</blockquote>
<p>Get a list of resources matching the supplied parameters.
This will return the first page of matching results. To retrieve additional pages, 
you can supply the <code>page</code> parameter to move through the full result set.</p>
<p>Parameters:</p>
<ul>
<li><code>resource_type</code> - one of Omeka's resource types, eg: 'items', 'properties'</li>
<li>there are many additional parameters you can supply as kwargs, see the Omeka documention</li>
</ul>
<p>Returns a dict with the following values:</p>
<ul>
<li><code>total_results</code> - number of matching resources</li>
<li><code>results</code> - a list of dicts, each containing a JSON-LD formatted representation of a resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;items&#39;</span><span class="p">)</span>
<span class="n">data</span><span class="p">[</span><span class="s1">&#39;total_results&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>120</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;total_results&#39;</span><span class="p">],</span> <span class="nb">int</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;resource_templates&#39;</span><span class="p">)</span>
<span class="n">first_template</span> <span class="o">=</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span>
<span class="k">assert</span> <span class="n">first_template</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:ResourceTemplate&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_resource_by_id" class="doc_header"><code>OmekaAPIClient.get_resource_by_id</code><a href="__main__.py#L101" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_resource_by_id</code>(<strong><code>resource_id</code></strong>, <strong><code>resource_type</code></strong>=<em><code>'items'</code></em>)</p>
</blockquote>
<p>Get a resource from its Omeka id.</p>
<p>Parameters:</p>
<ul>
<li><code>resource_id</code> - numeric identifier used by Omeka for this resource</li>
<li><code>resource_type</code> - one of Omeka's resource types, eg: 'items', 'properties'</li>
</ul>
<p>Returns</p>
<ul>
<li>a dict containing a JSON-LD formatted representation of the resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;items&#39;</span><span class="p">)</span>
<span class="n">random_item</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">item_id</span> <span class="o">=</span> <span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Get the same item using its id</span>
<span class="n">item_from_id</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resource_by_id</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="s1">&#39;items&#39;</span><span class="p">)</span>

<span class="c1"># Check that they&#39;re the same</span>
<span class="k">assert</span> <span class="n">random_item</span> <span class="o">==</span> <span class="n">item_from_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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 <code>get_resources</code>.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_template_by_label" class="doc_header"><code>OmekaAPIClient.get_template_by_label</code><a href="__main__.py#L116" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_template_by_label</code>(<strong><code>label</code></strong>)</p>
</blockquote>
<p>Get a resource template from its Omeka label.</p>
<p>Parameters:</p>
<ul>
<li><code>label</code> - the name of the resource template in Omeka (eg. 'NewspaperArticle')</li>
</ul>
<p>Returns:</p>
<ul>
<li>dict containing representation of the template</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">newspaper_template</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="s1">&#39;Newspaper&#39;</span><span class="p">)</span>

<span class="k">assert</span> <span class="n">newspaper_template</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:ResourceTemplate&#39;</span>
<span class="k">assert</span> <span class="n">newspaper_template</span><span class="p">[</span><span class="s1">&#39;o:label&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;Newspaper&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">template_from_list</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">omeka</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;resource_templates&#39;</span><span class="p">)[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">label</span> <span class="o">=</span> <span class="n">template_from_list</span><span class="p">[</span><span class="s1">&#39;o:label&#39;</span><span class="p">]</span>

<span class="c1"># Get the template using label</span>
<span class="n">template_from_label</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="n">label</span><span class="p">)</span>

<span class="c1"># Check they&#39;re both the same</span>
<span class="k">assert</span> <span class="n">template_from_list</span> <span class="o">==</span> <span class="n">template_from_label</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_resource_by_term" class="doc_header"><code>OmekaAPIClient.get_resource_by_term</code><a href="__main__.py#L128" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_resource_by_term</code>(<strong><code>term</code></strong>, <strong><code>resource_type</code></strong>=<em><code>'properties'</code></em>)</p>
</blockquote>
<p>Get the resource (property or class) associated with the suppied term.</p>
<p>Parameters:</p>
<ul>
<li><code>term</code> - property label qualified with vocabulary prefix (eg: 'schema:name')</li>
</ul>
<p>Returns:</p>
<ul>
<li>dict containing representation of the resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">prop</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resource_by_term</span><span class="p">(</span><span class="s1">&#39;schema:name&#39;</span><span class="p">)</span>
<span class="n">prop</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;@context&#39;: &#39;http://timsherratt.org/collections/api-context&#39;,
 &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/properties/1116&#39;,
 &#39;@type&#39;: &#39;o:Property&#39;,
 &#39;o:id&#39;: 1116,
 &#39;o:local_name&#39;: &#39;name&#39;,
 &#39;o:label&#39;: &#39;name&#39;,
 &#39;o:comment&#39;: &#39;The name of the item.&#39;,
 &#39;o:term&#39;: &#39;schema:name&#39;,
 &#39;o:vocabulary&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/vocabularies/5&#39;,
  &#39;o:id&#39;: 5}}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">prop</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:Property&#39;</span>
<span class="k">assert</span> <span class="n">prop</span><span class="p">[</span><span class="s1">&#39;o:term&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;schema:name&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_resource_from_vocab" class="doc_header"><code>OmekaAPIClient.get_resource_from_vocab</code><a href="__main__.py#L140" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_resource_from_vocab</code>(<strong><code>local_name</code></strong>, <strong><code>vocabulary_namespace_uri</code></strong>=<em><code>'http://schema.org/'</code></em>, <strong><code>resource_type</code></strong>=<em><code>'properties'</code></em>)</p>
</blockquote>
<p>Get the resource (property or class) associated with the suppied vocabulary and label.</p>
<p>Parameters:</p>
<ul>
<li><code>local_name</code> - label of the property or class</li>
<li><code>vocabulary_namespace_uri</code> - URI defining the vocab</li>
</ul>
<p>Returns:</p>
<ul>
<li>dict containing representation of the resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">prop</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resource_from_vocab</span><span class="p">(</span>
    <span class="s1">&#39;name&#39;</span><span class="p">,</span> 
    <span class="n">vocabulary_namespace_uri</span><span class="o">=</span><span class="s1">&#39;http://schema.org/&#39;</span><span class="p">,</span>
    <span class="n">resource_type</span><span class="o">=</span><span class="s1">&#39;properties&#39;</span><span class="p">)</span>
<span class="n">prop</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;@context&#39;: &#39;http://timsherratt.org/collections/api-context&#39;,
 &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/properties/1116&#39;,
 &#39;@type&#39;: &#39;o:Property&#39;,
 &#39;o:id&#39;: 1116,
 &#39;o:local_name&#39;: &#39;name&#39;,
 &#39;o:label&#39;: &#39;name&#39;,
 &#39;o:comment&#39;: &#39;The name of the item.&#39;,
 &#39;o:term&#39;: &#39;schema:name&#39;,
 &#39;o:vocabulary&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/vocabularies/5&#39;,
  &#39;o:id&#39;: 5}}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">vocab</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">prop</span><span class="p">[</span><span class="s1">&#39;o:vocabulary&#39;</span><span class="p">][</span><span class="s1">&#39;@id&#39;</span><span class="p">])</span>
<span class="n">namespace_uri</span> <span class="o">=</span> <span class="n">vocab</span><span class="o">.</span><span class="n">json</span><span class="p">()[</span><span class="s1">&#39;o:namespace_uri&#39;</span><span class="p">]</span>

<span class="k">assert</span> <span class="n">namespace_uri</span> <span class="o">==</span> <span class="s1">&#39;http://schema.org/&#39;</span>
<span class="k">assert</span> <span class="n">prop</span><span class="p">[</span><span class="s1">&#39;o:local_name&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;name&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_property_id" class="doc_header"><code>OmekaAPIClient.get_property_id</code><a href="__main__.py#L153" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_property_id</code>(<strong><code>term</code></strong>)</p>
</blockquote>
<p>Get the numeric identifier associated with the supplied property term.</p>
<p>Parameters:</p>
<ul>
<li><code>term</code> - property label qualified with vocabulary prefix (eg: 'schema:name')</li>
</ul>
<p>Returns:</p>
<ul>
<li>numeric identifier</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">prop_id</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_property_id</span><span class="p">(</span><span class="s1">&#39;schema:name&#39;</span><span class="p">)</span>
<span class="n">prop_id</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>1116</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">prop_id</span><span class="p">,</span> <span class="nb">int</span><span class="p">)</span>

<span class="n">prop</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resource_by_id</span><span class="p">(</span><span class="n">prop_id</span><span class="p">,</span> <span class="s1">&#39;properties&#39;</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">prop</span><span class="p">[</span><span class="s1">&#39;o:term&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;schema:name&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.filter_items_by_property" class="doc_header"><code>OmekaAPIClient.filter_items_by_property</code><a href="__main__.py#L174" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.filter_items_by_property</code>(<strong><code>filter_property</code></strong>=<em><code>'schema:name'</code></em>, <strong><code>filter_value</code></strong>=<em><code>''</code></em>, <strong><code>filter_type</code></strong>=<em><code>'eq'</code></em>, <strong><code>page</code></strong>=<em><code>1</code></em>, <strong>**<code>extra_filters</code></strong>)</p>
</blockquote>
<p>Filter the list of items by searching for a value in a particular property.
Additional filters can also limit to items associated with particular templates, classes, or item sets.</p>
<p>Parameters:</p>
<ul>
<li><code>filter_property</code> - property term (eg: 'schema:name')</li>
<li><code>filter_value</code> - the value you want to find</li>
<li><code>filter_type</code> - how <code>filter_value</code> should be compared to the stored values (eg: 'eq')</li>
<li><code>page</code> - number of results page</li>
</ul>
<p>Additional parameters:</p>
<ul>
<li><code>resource_template_id</code> - numeric identifier</li>
<li><code>resource_class_id</code> - numeric identifier</li>
<li><code>item_set_id</code> - numeric identifier</li>
<li><code>is_public</code> - boolean, True or False</li>
</ul>
<p>Returns a dict with the following values:</p>
<ul>
<li><code>total_results</code> - number of matching resources</li>
<li><code>results</code> - a list of dicts, each containing a JSON-LD formatted representation of a resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">items</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">filter_items_by_property</span><span class="p">(</span><span class="n">filter_property</span><span class="o">=</span><span class="s1">&#39;schema:name&#39;</span><span class="p">,</span> <span class="n">filter_value</span><span class="o">=</span><span class="s1">&#39;wragge&#39;</span><span class="p">,</span> <span class="n">filter_type</span><span class="o">=</span><span class="s1">&#39;in&#39;</span><span class="p">)</span>

<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">items</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span> <span class="o">&gt;</span> <span class="mi">0</span>
<span class="k">assert</span> <span class="s1">&#39;wragge&#39;</span> <span class="ow">in</span> <span class="n">items</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">items</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>&#39;Clement Wragge at Home. - UPDATED! - UPDATED!&#39;</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.search_items" class="doc_header"><code>OmekaAPIClient.search_items</code><a href="__main__.py#L210" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.search_items</code>(<strong><code>query</code></strong>, <strong><code>search_type</code></strong>=<em><code>'fulltext_search'</code></em>, <strong><code>page</code></strong>=<em><code>1</code></em>, <strong>**<code>extra_filters</code></strong>)</p>
</blockquote>
<p>Search for matching items.
Two search types are available:</p>
<ul>
<li>'search` - looks for an exact match of the query in a property value</li>
<li>'fulltext_search` - looks for the occurance of the query anywhere</li>
</ul>
<p>Parameters:</p>
<ul>
<li><code>query</code> - the text you want to search for</li>
<li><code>search_type</code> - one of 'fulltext_search' or 'search'</li>
<li><code>page</code> - number of results page</li>
</ul>
<p>Additional parameters:</p>
<ul>
<li><code>resource_template_id</code> - numeric identifier</li>
<li><code>resource_class_id</code> - numeric identifier</li>
<li><code>item_set_id</code> - numeric identifier</li>
<li><code>is_public</code> - boolean, True or False</li>
</ul>
<p>Returns a dict with the following values:</p>
<ul>
<li><code>total_results</code> - number of matching resources</li>
<li><code>results</code> - a list of dicts, each containing a JSON-LD formatted representation of a resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">items</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">search_items</span><span class="p">(</span><span class="s1">&#39;wragge&#39;</span><span class="p">)</span>
<span class="n">items</span><span class="p">[</span><span class="s1">&#39;total_results&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>23</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">items</span><span class="p">[</span><span class="s1">&#39;total_results&#39;</span><span class="p">]</span> <span class="o">&gt;=</span> <span class="nb">len</span><span class="p">(</span><span class="n">items</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Adding-items">Adding items<a class="anchor-link" href="#Adding-items"> </a></h2><p>To add resources to Omeka you need authenticate your API requests by supplying <code>key_identity</code> and <code>key_credential</code> tokens as parameters.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka_auth</span> <span class="o">=</span> <span class="n">OmekaAPIClient</span><span class="p">(</span>
    <span class="n">api_url</span><span class="o">=</span><span class="s1">&#39;https://timsherratt.org/collections/api&#39;</span><span class="p">,</span>
    <span class="n">key_identity</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_IDENTITY&#39;</span><span class="p">),</span> 
    <span class="n">key_credential</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_CREDENTIAL&#39;</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>There are two stages in creating a new item:</p>
<ul>
<li>prepare a payload containing the item data in the format expected by Omeka</li>
<li>upload the payload to Omeka</li>
</ul>
<h3 id="Prepare-an-item-payload">Prepare an item payload<a class="anchor-link" href="#Prepare-an-item-payload"> </a></h3>
</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.prepare_item_payload" class="doc_header"><code>OmekaAPIClient.prepare_item_payload</code><a href="__main__.py#L336" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.prepare_item_payload</code>(<strong><code>terms</code></strong>)</p>
</blockquote>
<p>Prepare an item payload, ready for upload.</p>
<p>Parameters:</p>
<ul>
<li><code>terms</code>: a dict of terms, values, and (optionally) data types</li>
</ul>
<p>Returns:</p>
<ul>
<li>the payload dict</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">test_item</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;dcterms:title&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;My first resource!&#39;</span>
        <span class="p">}</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload</span><span class="p">(</span><span class="n">test_item</span><span class="p">)</span>
<span class="n">payload</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;dcterms:title&#39;: [{&#39;property_id&#39;: 1,
   &#39;type&#39;: &#39;literal&#39;,
   &#39;@value&#39;: &#39;My first resource!&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Each term in the payload should have values for <code>property_id</code> and <code>type</code>, and the property value should be included as either <code>@id</code> or <code>@value</code> depending on the data type.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">first_property</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">payload</span><span class="o">.</span><span class="n">values</span><span class="p">())[</span><span class="mi">0</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span>

<span class="k">assert</span> <span class="s1">&#39;property_id&#39;</span> <span class="ow">in</span> <span class="n">first_property</span>
<span class="k">assert</span> <span class="s1">&#39;type&#39;</span> <span class="ow">in</span> <span class="n">first_property</span>
<span class="k">assert</span> <span class="s1">&#39;@value&#39;</span> <span class="ow">in</span> <span class="n">first_property</span> <span class="ow">or</span> <span class="s1">&#39;@id&#39;</span> <span class="ow">in</span> <span class="n">first_property</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.prepare_item_payload_using_template" class="doc_header"><code>OmekaAPIClient.prepare_item_payload_using_template</code><a href="__main__.py#L360" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.prepare_item_payload_using_template</code>(<strong><code>terms</code></strong>, <strong><code>template_id</code></strong>)</p>
</blockquote>
<p>Prepare an item payload, checking the supplied terms and values against the specified template.
Note:</p>
<ul>
<li>terms that are not in the template will generate a warning and be dropped from the payload</li>
<li>data types that don't match the template definitions will generate a warning and the term will be dropped from the payload</li>
<li>if no data type is supplied, a type that conforms with the template definition will be used</li>
</ul>
<p>Parameters:</p>
<ul>
<li><code>terms</code>: a dict of terms, values, and (optionally) data types</li>
<li><code>template_id</code>: Omeka's internal numeric identifier for the template</li>
</ul>
<p>Returns:</p>
<ul>
<li>the payload dict</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Once you've created a payload, you can add paths to any media files that you want to be attached to the item.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">test_newspaper_item</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;schema:name&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;Wragge!&#39;</span>
        <span class="p">}</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">test_newspaper_payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload_using_template</span><span class="p">(</span><span class="n">test_newspaper_item</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="n">test_newspaper_payload</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;schema:name&#39;: [{&#39;property_id&#39;: 1116,
   &#39;type&#39;: &#39;literal&#39;,
   &#39;@value&#39;: &#39;Wragge!&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">test_newspaper_item</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;value&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">test_newspaper_payload</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>
<span class="k">assert</span> <span class="n">test_newspaper_payload</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;literal&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.add_media_to_payload" class="doc_header"><code>OmekaAPIClient.add_media_to_payload</code><a href="__main__.py#L406" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.add_media_to_payload</code>(<strong><code>payload</code></strong>, <strong><code>media_files</code></strong>)</p>
</blockquote>
<p>Add media files to the item payload.</p>
<p>Parameters:</p>
<ul>
<li><code>payload</code> - the payload dict to be modified</li>
<li><code>media_files</code> - media files to be uploaded</li>
</ul>
<p>The value of <code>media_files</code> can be either:</p>
<ul>
<li>a list of paths to the image/media files (filename is used as title)</li>
<li>a list of dicts, each containing <code>title</code>, and <code>path</code> values</li>
</ul>
<p>The path values can either be strings or pathlib Paths.</p>
<p>Returns:</p>
<ul>
<li>the modified payload dict</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">payload_with_media</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_media_to_payload</span><span class="p">({},</span> <span class="n">media_files</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">])</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">payload_with_media</span><span class="p">[</span><span class="s1">&#39;data&#39;</span><span class="p">][</span><span class="mi">1</span><span class="p">])</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="Upload-the-payload-to-Omeka-and-create-a-new-item">Upload the payload to Omeka and create a new item<a class="anchor-link" href="#Upload-the-payload-to-Omeka-and-create-a-new-item"> </a></h3>
</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.add_item" class="doc_header"><code>OmekaAPIClient.add_item</code><a href="__main__.py#L303" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.add_item</code>(<strong><code>payload</code></strong>, <strong><code>media_files</code></strong>=<em><code>None</code></em>, <strong><code>template_id</code></strong>=<em><code>None</code></em>, <strong><code>class_id</code></strong>=<em><code>None</code></em>, <strong><code>item_set_id</code></strong>=<em><code>None</code></em>)</p>
</blockquote>
<p>Create a new item from the supplied payload, optionally uploading attached media files.</p>
<p>Parameters:</p>
<ul>
<li><code>payload</code> - a dict generated by <code>prepare_item_payload()</code> or <code>prepare_item_payload_using_template()</code></li>
<li><code>media_files</code> - a list of paths pointing to media files, or a list of dicts with <code>path</code> and <code>title</code> values</li>
<li><code>template_id</code> - internal Omeka identifier of a resource template you want to attach to this item</li>
<li><code>class_id</code> - internal Omeka identifier of a resource class you want to attach to this item</li>
<li><code>item_set_id</code> - internal Omeka identifier for an item set you want to add this item to</li>
</ul>
<p>Returns:</p>
<ul>
<li>a dict providing the JSON-LD representation of the new item from Omeka</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h3 id="Add-a-simple-item">Add a simple item<a class="anchor-link" href="#Add-a-simple-item"> </a></h3>
</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">new_item</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_item</span><span class="p">(</span><span class="n">payload</span><span class="p">)</span>
<span class="n">new_item</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;@context&#39;: &#39;https://timsherratt.org/collections/api-context&#39;,
 &#39;@id&#39;: &#39;https://timsherratt.org/collections/api/items/1038&#39;,
 &#39;@type&#39;: &#39;o:Item&#39;,
 &#39;o:id&#39;: 1038,
 &#39;o:is_public&#39;: True,
 &#39;o:owner&#39;: {&#39;@id&#39;: &#39;https://timsherratt.org/collections/api/users/1&#39;,
  &#39;o:id&#39;: 1},
 &#39;o:resource_class&#39;: None,
 &#39;o:resource_template&#39;: None,
 &#39;o:thumbnail&#39;: None,
 &#39;o:title&#39;: &#39;My first resource!&#39;,
 &#39;thumbnail_display_urls&#39;: {&#39;large&#39;: None, &#39;medium&#39;: None, &#39;square&#39;: None},
 &#39;o:created&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:47:02+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:modified&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:47:02+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:media&#39;: [],
 &#39;o:item_set&#39;: [],
 &#39;o:site&#39;: [],
 &#39;dcterms:title&#39;: [{&#39;type&#39;: &#39;literal&#39;,
   &#39;property_id&#39;: 1,
   &#39;property_label&#39;: &#39;Title&#39;,
   &#39;is_public&#39;: True,
   &#39;@value&#39;: &#39;My first resource!&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">new_item</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:Item&#39;</span>
<span class="k">assert</span> <span class="n">test_item</span><span class="p">[</span><span class="s1">&#39;dcterms:title&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;value&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">new_item</span><span class="p">[</span><span class="s1">&#39;dcterms:title&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>You can also add an item to an existing item set by supplying the <code>item_set_id</code> parameter.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">random_item_set</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;item_sets&#39;</span><span class="p">)[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">item_set_id</span> <span class="o">=</span> <span class="n">random_item_set</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Create a new item using the item set id</span>
<span class="n">new_item_in_item_set</span> <span class="o">=</span> <span class="n">new_item</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_item</span><span class="p">(</span><span class="n">payload</span><span class="p">,</span> <span class="n">item_set_id</span><span class="o">=</span><span class="n">item_set_id</span><span class="p">)</span>

<span class="c1"># Check that the ids match</span>
<span class="k">assert</span> <span class="n">new_item_in_item_set</span><span class="p">[</span><span class="s1">&#39;o:item_set&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">item_set_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Updating-resources">Updating resources<a class="anchor-link" href="#Updating-resources"> </a></h2>
</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.delete_resource" class="doc_header"><code>OmekaAPIClient.delete_resource</code><a href="__main__.py#L440" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.delete_resource</code>(<strong><code>resource_id</code></strong>, <strong><code>resource_type</code></strong>)</p>
</blockquote>
<p>Deletes a resource. No confirmation is requested, so use carefully.</p>
<p>Parameters:</p>
<ul>
<li><code>resource_id</code> - local Omeka identifier of the resource you want to delete</li>
<li><code>resource_type</code> - type of the resource (eg 'items')</li>
</ul>
<p>Returns:</p>
<ul>
<li>dict with JSON-LD representation of the deleted resource</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;items&#39;</span><span class="p">)</span>
<span class="n">random_item</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>

<span class="n">deleted_resource</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">delete_resource</span><span class="p">(</span><span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">],</span> <span class="s1">&#39;items&#39;</span><span class="p">)</span>

<span class="c1"># The id of the deleted item should be None</span>
<span class="k">assert</span> <span class="n">deleted_resource</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span>

<span class="c1"># The titles of the random and deleted items should be the same</span>
<span class="k">assert</span> <span class="n">deleted_resource</span><span class="p">[</span><span class="s1">&#39;o:title&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;o:title&#39;</span><span class="p">]</span>

<span class="c1"># Trying to get the random item should now raise an HTTP 404 error</span>
<span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">raises</span><span class="p">(</span><span class="n">requests</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">HTTPError</span><span class="p">):</span>
    <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resource_by_id</span><span class="p">(</span><span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">],</span> <span class="s1">&#39;items&#39;</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.update_resource" class="doc_header"><code>OmekaAPIClient.update_resource</code><a href="__main__.py#L455" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.update_resource</code>(<strong><code>payload</code></strong>, <strong><code>resource_type</code></strong>=<em><code>'items'</code></em>)</p>
</blockquote>
<p>Update an existing resource.</p>
<p>Parameters:</p>
<ul>
<li><code>payload</code> - the updated resource data</li>
<li><code>resource_type</code> - the type of resource</li>
</ul>
<p>To avoid problems, it's generally easiest to retrieve the resource first,
make your desired changes to it, then submit the updated resource as your payload.</p>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">filter_items_by_property</span><span class="p">(</span><span class="n">filter_property</span><span class="o">=</span><span class="s1">&#39;schema:name&#39;</span><span class="p">,</span> <span class="n">filter_type</span><span class="o">=</span><span class="s1">&#39;ex&#39;</span><span class="p">)</span>
<span class="n">random_item</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="c1"># Original title</span>
<span class="n">title</span> <span class="o">=</span> <span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>

<span class="c1"># Copy and update the original item</span>
<span class="n">new_item</span> <span class="o">=</span> <span class="n">deepcopy</span><span class="p">(</span><span class="n">random_item</span><span class="p">)</span>
<span class="n">new_item</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">title</span> <span class="o">+</span> <span class="s1">&#39; - UPDATED!&#39;</span>

<span class="c1"># Update the item </span>
<span class="n">updated_item</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">update_resource</span><span class="p">(</span><span class="n">new_item</span><span class="p">,</span> <span class="s1">&#39;items&#39;</span><span class="p">)</span>

<span class="c1"># Display the updated title</span>
<span class="n">updated_title</span> <span class="o">=</span> <span class="n">updated_item</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>
<span class="nb">print</span><span class="p">(</span><span class="n">updated_title</span><span class="p">)</span>

<span class="c1"># The id of the original and upated items should be the same</span>
<span class="k">assert</span> <span class="n">random_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">updated_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># But the titles should be different</span>
<span class="k">assert</span> <span class="n">title</span> <span class="o">!=</span> <span class="n">updated_item</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">

<div class="output_subarea output_stream output_stdout output_text">
<pre>Wellington Times (NSW : 1899 - 1954) - UPDATED! - UPDATED! - UPDATED!
</pre>
</div>
</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.add_media_to_item" class="doc_header"><code>OmekaAPIClient.add_media_to_item</code><a href="__main__.py#L470" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.add_media_to_item</code>(<strong><code>item_id</code></strong>, <strong><code>media_file</code></strong>, <strong><code>payload</code></strong>=<em><code>{}</code></em>, <strong><code>template_id</code></strong>=<em><code>None</code></em>, <strong><code>class_id</code></strong>=<em><code>None</code></em>)</p>
</blockquote>
<p>Upload a media file and associate it with an existing item.</p>
<p>Parameters:</p>
<ul>
<li><code>item_id</code> - the Omeka id of the item this media file should be added to</li>
<li><code>media_path</code> - a path to an image/media file (string or pathlib Path)</li>
<li><code>payload</code> (optional) - metadata to attach to media object, either 
 a dict generated by <code>prepare_item_payload()</code> or <code>prepare_item_payload_using_template()</code>,
 or a string which is used as the value for <code>dcterms:title</code>.</li>
<li><code>template_id</code> - internal Omeka identifier of a resource template you want to attach to this item</li>
<li><code>class_id</code> - internal Omeka identifier of a resource class you want to attach to this item</li>
</ul>
<p>Returns:</p>
<ul>
<li>a dict providing a JSON-LD representation of the new media object</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka_auth</span> <span class="o">=</span> <span class="n">OmekaAPIClient</span><span class="p">(</span>
    <span class="n">api_url</span><span class="o">=</span><span class="s1">&#39;https://timsherratt.org/collections/api&#39;</span><span class="p">,</span>
    <span class="n">key_identity</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_IDENTITY&#39;</span><span class="p">),</span> 
    <span class="n">key_credential</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_CREDENTIAL&#39;</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Add a media file to an item without any additional metadata.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;items&#39;</span><span class="p">)</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">item_id</span> <span class="o">=</span> <span class="n">item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Add a new media file to the item</span>
<span class="n">media_resource</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_media_to_item</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">)</span>

<span class="c1"># Check that the media resource is the expected type</span>
<span class="k">assert</span> <span class="n">media_resource</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:Media&#39;</span>

<span class="c1"># Check that the media resource is linked to the item</span>
<span class="k">assert</span> <span class="n">media_resource</span><span class="p">[</span><span class="s1">&#39;o:item&#39;</span><span class="p">][</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">item_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Include a title for a new media item by supplying a string value to the <code>payload</code> parameter.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">media_resource</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_media_to_item</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">,</span> <span class="n">payload</span><span class="o">=</span><span class="s1">&#39;This has a title&#39;</span><span class="p">)</span>

<span class="c1"># The title should be saved as dcterms:title</span>
<span class="k">assert</span> <span class="n">media_resource</span><span class="p">[</span><span class="s1">&#39;dcterms:title&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;This has a title&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Include more detailed metadata with a new media item by generating a payload and supplying it using the <code>payload</code> parameter.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">media_metadata</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;schema:name&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;This is a different title&#39;</span><span class="p">],</span>
    <span class="s1">&#39;schema:identifier&#39;</span><span class="p">:</span> <span class="p">[</span><span class="s1">&#39;myidis3&#39;</span><span class="p">]</span>
<span class="p">}</span>

<span class="c1"># Convert metadata into an Omeka payload</span>
<span class="n">media_payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload</span><span class="p">(</span><span class="n">media_metadata</span><span class="p">)</span>

<span class="c1"># Add a new media file with a metadata payload to the item</span>
<span class="n">media_resource</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_media_to_item</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">,</span> <span class="n">payload</span><span class="o">=</span><span class="n">media_payload</span><span class="p">)</span>

<span class="k">assert</span> <span class="n">media_resource</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">][</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;@value&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;This is a different title&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Use a specific resource template with the new media item by using the <code>template_id</code> parameter.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;resource_templates&#39;</span><span class="p">)</span>
<span class="n">template</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">template_id</span> <span class="o">=</span> <span class="n">template</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Add a new media file and assign it to a template using the `template_id` parameter</span>
<span class="n">media_resource</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_media_to_item</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">,</span> <span class="n">payload</span><span class="o">=</span><span class="n">media_payload</span><span class="p">,</span> <span class="n">template_id</span><span class="o">=</span><span class="n">template_id</span><span class="p">)</span>

<span class="c1"># Check the new media object has the correct template id</span>
<span class="k">assert</span> <span class="n">media_resource</span><span class="p">[</span><span class="s1">&#39;o:resource_template&#39;</span><span class="p">][</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">template_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.add_marker_to_item" class="doc_header"><code>OmekaAPIClient.add_marker_to_item</code><a href="__main__.py#L653" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.add_marker_to_item</code>(<strong><code>item_id</code></strong>, <strong><code>coords</code></strong>=<em><code>None</code></em>, <strong><code>terms</code></strong>=<em><code>None</code></em>, <strong><code>label</code></strong>=<em><code>None</code></em>, <strong><code>media_id</code></strong>=<em><code>None</code></em>)</p>
</blockquote>
<p>Add a map marker to an item.
Requires the <code>mapping</code> module to be installed.</p>
<p>Parameters:</p>
<ul>
<li><code>item_id</code> - identifier of item to add marker to</li>
<li><code>coords</code> - list with coordinates in longitude, latitude order eg [151.209900, -33.865143]</li>
<li><code>terms</code> - list with vocab terms containing longitude and latitude values eg ['schema:longitude', 'schema:latitude']</li>
<li><code>label</code> - label for marker (defaults to item title)</li>
<li><code>media_id</code> - identifier of media resource to display with marker</li>
</ul>
<p>Returns:</p>
<ul>
<li>dict providing JSON-LD representation of marker</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>The Omeka <a href="https://omeka.org/s/modules/Mapping/">Mapping</a> module lets you associate an item with a location on a map. Once you have the module installed, you can use the Omeka API to add map markers to items.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resources</span><span class="p">(</span><span class="s1">&#39;items&#39;</span><span class="p">)</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">choice</span><span class="p">(</span><span class="n">data</span><span class="p">[</span><span class="s1">&#39;results&#39;</span><span class="p">])</span>
<span class="n">item_id</span> <span class="o">=</span> <span class="n">item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Add a marker using coords</span>
<span class="n">marker</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_marker_to_item</span><span class="p">(</span><span class="n">item_id</span><span class="p">,</span> <span class="n">coords</span><span class="o">=</span><span class="p">[</span><span class="mf">151.209900</span><span class="p">,</span> <span class="o">-</span><span class="mf">33.865143</span><span class="p">])</span>

<span class="k">assert</span> <span class="n">marker</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o-module-mapping:Marker&#39;</span>
<span class="k">assert</span> <span class="n">marker</span><span class="p">[</span><span class="s1">&#39;o:item&#39;</span><span class="p">][</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">item_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>You can also read the map coordinates from the item itself. By default <a href="/omeka_s_tools/api.html#OmekaAPIClient.add_marker_to_item"><code>OmekaAPIClient.add_marker_to_item</code></a> will look for values in <code>schema:longitude</code> and <code>schema:latitude</code>, but you can specify the vocabulary terms that you want to look for.</p>
<p>Here we'll create a simple item with values for <code>schema:longitude</code> and <code>schema:latitude</code>.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">test_place</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;schema:name&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;Australia&#39;</span>
        <span class="p">}</span>
    <span class="p">],</span>
    <span class="s1">&#39;schema:longitude&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;151.209900&#39;</span>
        <span class="p">}</span>
    <span class="p">],</span>
    <span class="s1">&#39;schema:latitude&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;-33.865143&#39;</span>
        <span class="p">}</span>
    <span class="p">],</span>
    
<span class="p">}</span>

<span class="n">payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload</span><span class="p">(</span><span class="n">test_place</span><span class="p">)</span>
<span class="n">new_place</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_item</span><span class="p">(</span><span class="n">payload</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Now we can just call <a href="/omeka_s_tools/api.html#OmekaAPIClient.add_marker_to_item"><code>OmekaAPIClient.add_marker_to_item</code></a> without any coordinates, and it will get them from <code>schema:longitude</code> and <code>schema:latitude</code>.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">new_marker</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_marker_to_item</span><span class="p">(</span><span class="n">new_place</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">])</span>

<span class="k">assert</span> <span class="n">new_marker</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o-module-mapping:Marker&#39;</span>
<span class="k">assert</span> <span class="n">new_marker</span><span class="p">[</span><span class="s1">&#39;o:item&#39;</span><span class="p">][</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">new_place</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>
<span class="k">assert</span> <span class="n">new_marker</span><span class="p">[</span><span class="s1">&#39;o-module-mapping:lat&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="o">-</span><span class="mf">33.865143</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Managing-templates">Managing templates<a class="anchor-link" href="#Managing-templates"> </a></h2><p>Resource templates can be exported from one Omeka instance and imported into another. This is a really useful way of sharing and resuing data structures. However, exported templates can't be uploaded via the API without some modification, as they don't include Omeka numeric identifiers for referenced classes and properties. Before uploading them, we need to find the referenced classes and properties in the local Omeka instance, and insert the local identifiers into the payload.</p>
<p>Similarly, if custom vocabs are referenced in the exported template, they will need to be updated to include the vocab's identifier in the new Omeka instance. Of course, you'll need to make sure it's installed first.</p>
<p>In general, you want to make sure that the any vocabs and data types referenced by the exported templates will be available in the new Omeka instance. So before you upload any templates you should check that:</p>
<ul>
<li>referenced vocabularies are already installed</li>
<li>modules used in defining data types are installed ( eg the <a href="https://omeka.org/s/modules/NumericDataTypes/">Numeric Data Types</a> module provides additional data types such as <code>Timestamp</code> for dates</li>
<li>any custom vocabularies (created using the <a href="https://omeka.org/s/modules/CustomVocab/">Custom Vocab</a> are installed, along with the module itself of course</li>
<li>the <a href="https://omeka.org/s/modules/ValueSuggest/">Value Suggest</a> module is installed if the template includes references to the controlled vocabs it provides</li>
</ul>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.prepare_template_payload" class="doc_header"><code>OmekaAPIClient.prepare_template_payload</code><a href="__main__.py#L583" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.prepare_template_payload</code>(<strong><code>template_file</code></strong>)</p>
</blockquote>
<p>Insert local property, class, and vocab identifiers into a resource template
exported from Omeka so that it can be uploaded to the local instance.</p>
<p>Parameters:</p>
<ul>
<li><code>template_file</code> - path to a template exported from Omeka (str or pathlib Path)</li>
</ul>
<p>Returns:</p>
<ul>
<li>template payload with local identifiers inserted</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka_auth</span> <span class="o">=</span> <span class="n">OmekaAPIClient</span><span class="p">(</span>
    <span class="n">api_url</span><span class="o">=</span><span class="s1">&#39;https://timsherratt.org/collections/api&#39;</span><span class="p">,</span>
    <span class="n">key_identity</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_IDENTITY&#39;</span><span class="p">),</span> 
    <span class="n">key_credential</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_CREDENTIAL&#39;</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">template_payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_template_payload</span><span class="p">(</span><span class="s1">&#39;templates/Person.json&#39;</span><span class="p">)</span>

<span class="c1"># Check the label</span>
<span class="k">assert</span> <span class="n">template_payload</span><span class="p">[</span><span class="s1">&#39;o:label&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;Person&#39;</span>

<span class="c1"># Check that there is a list of properties</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">template_payload</span><span class="p">[</span><span class="s1">&#39;o:resource_template_property&#39;</span><span class="p">])</span> <span class="o">&gt;</span> <span class="mi">0</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.upload_template" class="doc_header"><code>OmekaAPIClient.upload_template</code><a href="__main__.py#L636" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.upload_template</code>(<strong><code>template_payload</code></strong>)</p>
</blockquote>
<p>Upload a template exported from an instance of Omeka to the current local instance.</p>
<p>Parameters:</p>
<ul>
<li><code>template_payload</code> - dict payload generated by <code>prepare_template_payload</code></li>
</ul>
<p>Return:</p>
<ul>
<li>dict containing a JSON-LD representation of the uploaded template</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">existing_template</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="s1">&#39;Person&#39;</span><span class="p">)</span>

<span class="c1"># If there is we&#39;ll delete it</span>
<span class="c1"># Trying to upload a template with the same label as an existing template will generate an error</span>
<span class="k">if</span> <span class="n">existing_template</span><span class="p">:</span>
    <span class="n">deleted</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">delete_resource</span><span class="p">(</span><span class="n">existing_template</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">],</span> <span class="s1">&#39;resource_templates&#39;</span><span class="p">)</span>

<span class="c1"># Now we can add the new template</span>
<span class="n">template_payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_template_payload</span><span class="p">(</span><span class="s1">&#39;templates/Person.json&#39;</span><span class="p">)</span>
<span class="n">new_template</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">upload_template</span><span class="p">(</span><span class="n">template_payload</span><span class="p">)</span>

<span class="c1"># Result should be a &#39;ResourceTemplate</span>
<span class="k">assert</span> <span class="n">new_template</span><span class="p">[</span><span class="s1">&#39;@type&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;o:ResourceTemplate&#39;</span>

<span class="c1"># Label should be &#39;Person&#39;</span>
<span class="k">assert</span> <span class="n">new_template</span><span class="p">[</span><span class="s1">&#39;o:label&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;Person&#39;</span>

<span class="c1"># It should have properties</span>
<span class="k">assert</span> <span class="nb">len</span><span class="p">(</span><span class="n">new_template</span><span class="p">[</span><span class="s1">&#39;o:resource_template_property&#39;</span><span class="p">])</span> <span class="o">&gt;</span> <span class="mi">0</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.localise_custom_vocabs" class="doc_header"><code>OmekaAPIClient.localise_custom_vocabs</code><a href="__main__.py#L517" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.localise_custom_vocabs</code>(<strong><code>data_types</code></strong>)</p>
</blockquote>
<p>Check a list of data types for references to custom vocabs.
If found, look for the local identifier of the custom vocab, 
and insert it into the data type information.</p>
<p>Parameters:</p>
<ul>
<li><code>data_types</code> - a list of data types from an exported template property</li>
</ul>
<p>Returns:</p>
<ul>
<li>list of datatypes with local identifiers</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">data_types</span> <span class="o">=</span> <span class="p">[{</span><span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;customvocab:200000&#39;</span><span class="p">,</span> <span class="s1">&#39;label&#39;</span><span class="p">:</span> <span class="s2">&quot;Date qualifiers&quot;</span><span class="p">}]</span>

<span class="c1"># Localise!</span>
<span class="n">localised_data_types</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">localise_custom_vocabs</span><span class="p">(</span><span class="n">data_types</span><span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">localised_data_types</span><span class="p">)</span>

<span class="c1"># Localised data type should start with &#39;customvocab&#39;</span>
<span class="k">assert</span> <span class="n">localised_data_types</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">&#39;customvocab:&#39;</span><span class="p">)</span>

<span class="c1"># The localised customvocab id should not be the same as the supplied one</span>
<span class="k">assert</span> <span class="n">localised_data_types</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">!=</span> <span class="n">data_types</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s1">&#39;name&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">

<div class="output_subarea output_stream output_stdout output_text">
<pre>[&#39;customvocab:1&#39;]
</pre>
</div>
</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_template_class_id" class="doc_header"><code>OmekaAPIClient.get_template_class_id</code><a href="__main__.py#L542" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_template_class_id</code>(<strong><code>template</code></strong>)</p>
</blockquote>
<p>Get the local id of the resource class associated with the supplied template.</p>
<p>Parameters:</p>
<ul>
<li><code>template</code> - dict from exported template</li>
</ul>
<p>Returns:</p>
<ul>
<li>class identifier</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">template</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s1">&#39;templates/Person.json&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">read_bytes</span><span class="p">())</span>

<span class="n">person_class_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resource_by_term</span><span class="p">(</span><span class="s1">&#39;schema:Person&#39;</span><span class="p">,</span> <span class="s1">&#39;resource_classes&#39;</span><span class="p">)[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Get resource id</span>
<span class="n">class_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_class_id</span><span class="p">(</span><span class="n">template</span><span class="p">)</span>

<span class="k">assert</span> <span class="n">class_id</span> <span class="o">==</span> <span class="n">person_class_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_template_property_id" class="doc_header"><code>OmekaAPIClient.get_template_property_id</code><a href="__main__.py#L562" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_template_property_id</code>(<strong><code>template</code></strong>, <strong><code>term</code></strong>)</p>
</blockquote>
<p>Get the local id of the property associated with the supplied template.</p>
<p>Parameters:</p>
<ul>
<li><code>template</code> - dict from exported template</li>
<li><code>term</code> - property term (eg 'o:title_property')</li>
</ul>
<p>Returns:</p>
<ul>
<li>property identifier</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">template</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s1">&#39;templates/Person.json&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">read_bytes</span><span class="p">())</span>

<span class="c1"># get the id of the schema:name property</span>
<span class="n">name_prop_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_resource_by_term</span><span class="p">(</span><span class="s1">&#39;schema:name&#39;</span><span class="p">,</span> <span class="s1">&#39;properties&#39;</span><span class="p">)[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>

<span class="c1"># Get id of template property used for title</span>
<span class="n">prop_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_property_id</span><span class="p">(</span><span class="n">template</span><span class="p">,</span> <span class="s1">&#39;o:title_property&#39;</span><span class="p">)</span>

<span class="c1"># The ids should be the same</span>
<span class="k">assert</span> <span class="n">prop_id</span> <span class="o">==</span> <span class="n">name_prop_id</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Utilities">Utilities<a class="anchor-link" href="#Utilities"> </a></h2>
</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.format_resource_id" class="doc_header"><code>OmekaAPIClient.format_resource_id</code><a href="__main__.py#L46" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.format_resource_id</code>(<strong><code>resource_id</code></strong>, <strong><code>resource_type</code></strong>)</p>
</blockquote>
<p>Generate a formatted id for the resource with the specified Omeka id number and resource type.</p>
<p>Parameters:</p>
<ul>
<li><code>resource_id</code> - numeric identifier used by Omeka for this resource</li>
<li><code>resource_type</code> - one of Omeka's resource types, eg: 'items', 'properties'</li>
</ul>
<p>Returns:</p>
<ul>
<li>a dict with values for '@id' and 'o:id'</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">id_url</span> <span class="o">=</span> <span class="n">omeka</span><span class="o">.</span><span class="n">format_resource_id</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="s1">&#39;resource_templates&#39;</span><span class="p">)</span>

<span class="k">assert</span> <span class="n">id_url</span> <span class="o">==</span> <span class="p">{</span>
    <span class="s1">&#39;@id&#39;</span><span class="p">:</span> <span class="s1">&#39;http://timsherratt.org/collections/api/resource_templates/5&#39;</span><span class="p">,</span>
    <span class="s1">&#39;o:id&#39;</span><span class="p">:</span> <span class="mi">5</span>
<span class="p">}</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.prepare_property_value" class="doc_header"><code>OmekaAPIClient.prepare_property_value</code><a href="__main__.py#L266" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.prepare_property_value</code>(<strong><code>value</code></strong>, <strong><code>property_id</code></strong>)</p>
</blockquote>
<p>Formats a property value according to its datatype as expected by Omeka. 
The formatted value can be used in a payload to create a new item.</p>
<p>Parameters:</p>
<ul>
<li><code>value</code> - a dict containing a <code>value</code> and (optionally) a <code>type</code></li>
<li><code>property_id</code> - the numeric identifier of the property</li>
</ul>
<p>Note that is no <code>type</code> is supplied, 'literal' will be used by default.</p>
<p>Returns:</p>
<ul>
<li>a dict with values for <code>property_id</code>, <code>type</code>, and either <code>@id</code> or <code>@value</code>.</li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">prop_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_property_id</span><span class="p">(</span><span class="s1">&#39;schema:url&#39;</span><span class="p">)</span>
<span class="n">prop_value</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;https://glam-workbench.net&#39;</span><span class="p">,</span> <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;uri&#39;</span><span class="p">}</span>

<span class="n">formatted_prop</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_property_value</span><span class="p">(</span><span class="n">prop_value</span><span class="p">,</span> <span class="n">prop_id</span><span class="p">)</span>
<span class="n">formatted_prop</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;property_id&#39;: 393, &#39;type&#39;: &#39;uri&#39;, &#39;@id&#39;: &#39;https://glam-workbench.net&#39;}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="k">assert</span> <span class="n">prop_id</span> <span class="o">==</span> <span class="n">formatted_prop</span><span class="p">[</span><span class="s1">&#39;property_id&#39;</span><span class="p">]</span>
<span class="k">assert</span> <span class="s1">&#39;type&#39;</span> <span class="ow">in</span> <span class="n">formatted_prop</span>
<span class="k">assert</span> <span class="n">formatted_prop</span><span class="p">[</span><span class="s1">&#39;@id&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="s1">&#39;https://glam-workbench.net&#39;</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">

<div class="output_wrapper">
<div class="output">

<div class="output_area">


<div class="output_markdown rendered_html output_subarea ">
<h4 id="OmekaAPIClient.get_template_properties" class="doc_header"><code>OmekaAPIClient.get_template_properties</code><a href="__main__.py#L238" class="source_link" style="float:right">[source]</a></h4><blockquote><p><code>OmekaAPIClient.get_template_properties</code>(<strong><code>template_id</code></strong>)</p>
</blockquote>
<p>List properties used by the specified template.</p>
<p>The resource template objects returned by the API don't include property terms.
This function gets the additional details, and organises the properties in a dictionary, 
organised by term. This makes it easy to check if a particular term is used by a template.</p>
<p>Parameters:</p>
<ul>
<li><code>template_id</code> - numeric identifier for a template</li>
</ul>
<p>Returns:</p>
<ul>
<li>a dict organised by property terms, with values for <code>property_id</code> and <code>type</code></li>
</ul>

</div>

</div>

</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">template_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="s1">&#39;Newspaper&#39;</span><span class="p">)[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>
<span class="n">newspaper_properties</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_properties</span><span class="p">(</span><span class="n">template_id</span><span class="p">)</span>

<span class="k">assert</span> <span class="s1">&#39;schema:name&#39;</span> <span class="ow">in</span> <span class="n">newspaper_properties</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h2 id="Example:-adding-a-newspaper-article-from-Trove">Example: adding a newspaper article from Trove<a class="anchor-link" href="#Example:-adding-a-newspaper-article-from-Trove"> </a></h2>
</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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. For a more detailed example that uploads Trove newspaper articles from a variety of sources, including Trove searches, Trove lists, and Zotero libraries, see the <a href="https://glam-workbench.net/trove-newspapers/#upload-trove-newspaper-articles-to-omeka-s">GLAM Workbench</a>.</p>
<p>Let's suppose we want to add <a href="http://nla.gov.au/nla.news-article226799674">this newspaper article</a> 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.</p>
<p>I've already created templates labelled 'Newspaper' and 'Newspaper article'.</p>
<p>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 <a href="/omeka_s_tools/api.html#OmekaAPIClient.get_template_by_label"><code>OmekaAPIClient.get_template_by_label</code></a> to find out.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka_auth</span> <span class="o">=</span> <span class="n">OmekaAPIClient</span><span class="p">(</span>
    <span class="n">api_url</span><span class="o">=</span><span class="s1">&#39;http://timsherratt.org/collections/api&#39;</span><span class="p">,</span>
    <span class="n">key_identity</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_IDENTITY&#39;</span><span class="p">),</span> 
    <span class="n">key_credential</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s1">&#39;KEY_CREDENTIAL&#39;</span><span class="p">)</span>
<span class="p">)</span>

<span class="n">newspaper_template_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="s1">&#39;Newspaper&#39;</span><span class="p">)[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>
<span class="n">newspaper_template_id</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>5</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>For convenience, we can get a summary of the properties used in the Newspaper template using <a href="/omeka_s_tools/api.html#OmekaAPIClient.get_template_properties"><code>OmekaAPIClient.get_template_properties</code></a>. This is useful if we want to check which properties are in use, and what data types are expected.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_properties</span><span class="p">(</span><span class="n">newspaper_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;schema:name&#39;: {&#39;property_id&#39;: 1116, &#39;type&#39;: [&#39;literal&#39;]},
 &#39;schema:additionalType&#39;: {&#39;property_id&#39;: 1199, &#39;type&#39;: [&#39;uri&#39;]},
 &#39;schema:description&#39;: {&#39;property_id&#39;: 528,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:alternateName&#39;: {&#39;property_id&#39;: 282,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:editor&#39;: {&#39;property_id&#39;: 752, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:publisher&#39;: {&#39;property_id&#39;: 967, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:issn&#39;: {&#39;property_id&#39;: 931,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:startDate&#39;: {&#39;property_id&#39;: 513, &#39;type&#39;: [&#39;numeric:timestamp&#39;]},
 &#39;schema:endDate&#39;: {&#39;property_id&#39;: 657, &#39;type&#39;: [&#39;numeric:timestamp&#39;]},
 &#39;schema:locationCreated&#39;: {&#39;property_id&#39;: 706, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:hasPart&#39;: {&#39;property_id&#39;: 1405, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:about&#39;: {&#39;property_id&#39;: 1392, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:mentions&#39;: {&#39;property_id&#39;: 747, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:contentLocation&#39;: {&#39;property_id&#39;: 1419, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:temporalCoverage&#39;: {&#39;property_id&#39;: 460,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:subjectOf&#39;: {&#39;property_id&#39;: 1391, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:url&#39;: {&#39;property_id&#39;: 393, &#39;type&#39;: [&#39;uri&#39;]},
 &#39;schema:image&#39;: {&#39;property_id&#39;: 742, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:identifier&#39;: {&#39;property_id&#39;: 190,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:sameAs&#39;: {&#39;property_id&#39;: 246, &#39;type&#39;: [&#39;uri&#39;]}}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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 <code>schema.name</code> and <code>schema.url</code>.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">newspaper</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;schema.name&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;literal&#39;</span><span class="p">,</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;</span>
        <span class="p">}</span>
    <span class="p">],</span>
    <span class="s1">&#39;schema:url&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;literal&#39;</span><span class="p">,</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;http://nla.gov.au/nla.news-title806&#39;</span>
        <span class="p">}</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Now we can use this data to create a payload for upload to Omeka. <a href="/omeka_s_tools/api.html#OmekaAPIClient.prepare_item_payload_using_template"><code>OmekaAPIClient.prepare_item_payload_using_template</code></a> will check our data against the Newspaper template and build the payload.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload_using_template</span><span class="p">(</span><span class="n">newspaper</span><span class="p">,</span> <span class="n">newspaper_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">

<div class="output_subarea output_stream output_stdout output_text">
<pre>Term schema.name not in template
Data type &#34;literal&#34; for term &#34;schema:url&#34; not allowed by template
</pre>
</div>
</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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 <code>schema:name</code>. Second, we've said the data type of <code>schema:url</code> is 'literal', but if we check the template properties we'll see it' should be 'uri'. Let's make these changes.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">newspaper</span> <span class="o">=</span> <span class="p">{</span>
    <span class="s1">&#39;schema:name&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;literal&#39;</span><span class="p">,</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;</span>
        <span class="p">}</span>
    <span class="p">],</span>
    <span class="s1">&#39;schema:url&#39;</span><span class="p">:</span> <span class="p">[</span>
        <span class="p">{</span>
            <span class="s1">&#39;type&#39;</span><span class="p">:</span> <span class="s1">&#39;uri&#39;</span><span class="p">,</span>
            <span class="s1">&#39;value&#39;</span><span class="p">:</span> <span class="s1">&#39;http://nla.gov.au/nla.news-title806&#39;</span>
        <span class="p">}</span>
    <span class="p">]</span>
<span class="p">}</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload_using_template</span><span class="p">(</span><span class="n">newspaper</span><span class="p">,</span> <span class="n">newspaper_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>That seems better! Now we can examine the payload.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">payload</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;schema:name&#39;: [{&#39;property_id&#39;: 1116,
   &#39;type&#39;: &#39;literal&#39;,
   &#39;@value&#39;: &#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;}],
 &#39;schema:url&#39;: [{&#39;property_id&#39;: 393,
   &#39;type&#39;: &#39;uri&#39;,
   &#39;@id&#39;: &#39;http://nla.gov.au/nla.news-title806&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Notice how the values have been reformatted? They should now be ready to upload to Omeka using <a href="/omeka_s_tools/api.html#OmekaAPIClient.add_item"><code>OmekaAPIClient.add_item</code></a>. We'll supply both the payload and the newspaper template id.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">newspaper_item</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_item</span><span class="p">(</span><span class="n">payload</span><span class="p">,</span> <span class="n">template_id</span><span class="o">=</span><span class="n">newspaper_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>We can check the contents of <code>newspaper_item</code> to make sure it's been added succesfully.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">newspaper_item</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;@context&#39;: &#39;http://timsherratt.org/collections/api-context&#39;,
 &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/items/1045&#39;,
 &#39;@type&#39;: [&#39;o:Item&#39;, &#39;schema:Newspaper&#39;],
 &#39;o:id&#39;: 1045,
 &#39;o:is_public&#39;: True,
 &#39;o:owner&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/users/1&#39;,
  &#39;o:id&#39;: 1},
 &#39;o:resource_class&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/resource_classes/161&#39;,
  &#39;o:id&#39;: 161},
 &#39;o:resource_template&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/resource_templates/5&#39;,
  &#39;o:id&#39;: 5},
 &#39;o:thumbnail&#39;: None,
 &#39;o:title&#39;: &#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;,
 &#39;thumbnail_display_urls&#39;: {&#39;large&#39;: None, &#39;medium&#39;: None, &#39;square&#39;: None},
 &#39;o:created&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:48:33+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:modified&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:48:33+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:media&#39;: [],
 &#39;o:item_set&#39;: [],
 &#39;o:site&#39;: [],
 &#39;schema:name&#39;: [{&#39;type&#39;: &#39;literal&#39;,
   &#39;property_id&#39;: 1116,
   &#39;property_label&#39;: &#39;name&#39;,
   &#39;is_public&#39;: True,
   &#39;@value&#39;: &#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;}],
 &#39;schema:url&#39;: [{&#39;type&#39;: &#39;uri&#39;,
   &#39;property_id&#39;: 393,
   &#39;property_label&#39;: &#39;url&#39;,
   &#39;is_public&#39;: True,
   &#39;@id&#39;: &#39;http://nla.gov.au/nla.news-title806&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Great! Now what about the article? Again let's start by having a look at the 'Newspaper article' template.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article_template_id</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_by_label</span><span class="p">(</span><span class="s1">&#39;Newspaper article&#39;</span><span class="p">)[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]</span>
<span class="n">omeka_auth</span><span class="o">.</span><span class="n">get_template_properties</span><span class="p">(</span><span class="n">article_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;schema:name&#39;: {&#39;property_id&#39;: 1116,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:additionalType&#39;: {&#39;property_id&#39;: 1199, &#39;type&#39;: [&#39;uri&#39;]},
 &#39;schema:description&#39;: {&#39;property_id&#39;: 528,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:alternateName&#39;: {&#39;property_id&#39;: 282,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:datePublished&#39;: {&#39;property_id&#39;: 928, &#39;type&#39;: [&#39;numeric:timestamp&#39;]},
 &#39;schema:pagination&#39;: {&#39;property_id&#39;: 376,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:creator&#39;: {&#39;property_id&#39;: 329, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:contributor&#39;: {&#39;property_id&#39;: 1303, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:isPartOf&#39;: {&#39;property_id&#39;: 736, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:license&#39;: {&#39;property_id&#39;: 1348,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:about&#39;: {&#39;property_id&#39;: 1392, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:mentions&#39;: {&#39;property_id&#39;: 747, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:contentLocation&#39;: {&#39;property_id&#39;: 1419, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:temporalCoverage&#39;: {&#39;property_id&#39;: 460,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:subjectOf&#39;: {&#39;property_id&#39;: 1391, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:image&#39;: {&#39;property_id&#39;: 742, &#39;type&#39;: [&#39;resource:item&#39;]},
 &#39;schema:url&#39;: {&#39;property_id&#39;: 393, &#39;type&#39;: [&#39;uri&#39;]},
 &#39;schema:identifier&#39;: {&#39;property_id&#39;: 190,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]},
 &#39;schema:sameAs&#39;: {&#39;property_id&#39;: 246, &#39;type&#39;: [&#39;uri&#39;]},
 &#39;schema:text&#39;: {&#39;property_id&#39;: 833,
  &#39;type&#39;: [&#39;literal&#39;, &#39;uri&#39;, &#39;resource:item&#39;]}}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>This time we'll build our data file in stages.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article</span> <span class="o">=</span> <span class="p">{}</span>

<span class="c1"># Add value for schema:name</span>
<span class="n">article</span><span class="p">[</span><span class="s1">&#39;schema:name&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;MR WRAGGE&#39;S PREDICTION. RENEWAL OF CYCLONE FORETOLD.&quot;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>You'll notice that this time I've only included the value of the property, not the data type. This is because <a href="/omeka_s_tools/api.html#OmekaAPIClient.prepare_item_payload_using_template"><code>OmekaAPIClient.prepare_item_payload_using_template</code></a> will insert default data types if they're not specified. The basic rules it uses if you don't supply a data type are:</p>
<ul>
<li>if the template defines a default data type, use that</li>
<li>if 'literal' is in the template's list of expected data types, use that</li>
<li>if 'literal' is not in the template's list of expected data types print a warning asking the user to specify a data type and drop the property from the payload</li>
</ul>
<p>In the case above, the 'literal' data type will be assigned to the <code>schema:name</code> value.</p>
<p>To create a link between the article and the newspaper it was published in, we can use <code>schema.isPartOf</code>. If we look in the list of template properties we see that this property expects a data type of 'resource:item'.</p>

<pre><code>'schema:isPartOf': {'property_id': 736, 'type': ['resource:item']}</code></pre>
<p>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.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article</span><span class="p">[</span><span class="s1">&#39;schema:isPartOf&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">newspaper_item</span><span class="p">[</span><span class="s1">&#39;o:id&#39;</span><span class="p">]]</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Next we'll add the publication date. To recognise dates as specific data types, you need to install the <a href="https://omeka.org/s/modules/NumericDataTypes/">Numeric Data Types</a> 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:</p>

<pre><code>'schema:datePublished': {'property_id': 928, 'type': ['numeric:timestamp']}</code></pre>
<p>The date value itself is supplied in a standard ISO format -- 'YYYY-MM-DD'.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article</span><span class="p">[</span><span class="s1">&#39;schema:datePublished&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;1918-03-14&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Finally we'll add a link to the article. Once again the template includes a default data type.</p>

<pre><code>'schema:url': {'property_id': 393, 'type': ['uri']}</code></pre>
<p>So we can just include the value.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article</span><span class="p">[</span><span class="s1">&#39;schema:url&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;http://nla.gov.au/nla.news-article226799674&#39;</span><span class="p">]</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Now that we've assembled the article metadata, we can generate a payload.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article_payload</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">prepare_item_payload_using_template</span><span class="p">(</span><span class="n">article</span><span class="p">,</span> <span class="n">article_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article_payload</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;schema:name&#39;: [{&#39;property_id&#39;: 1116,
   &#39;type&#39;: &#39;literal&#39;,
   &#39;@value&#39;: &#34;MR WRAGGE&#39;S PREDICTION. RENEWAL OF CYCLONE FORETOLD.&#34;}],
 &#39;schema:isPartOf&#39;: [{&#39;property_id&#39;: 736,
   &#39;type&#39;: &#39;resource:item&#39;,
   &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/items/1045&#39;,
   &#39;value_resource_id&#39;: 1045,
   &#39;value_resource_name&#39;: &#39;items&#39;}],
 &#39;schema:datePublished&#39;: [{&#39;property_id&#39;: 928,
   &#39;type&#39;: &#39;numeric:timestamp&#39;,
   &#39;@value&#39;: &#39;1918-03-14&#39;}],
 &#39;schema:url&#39;: [{&#39;property_id&#39;: 393,
   &#39;type&#39;: &#39;uri&#39;,
   &#39;@id&#39;: &#39;http://nla.gov.au/nla.news-article226799674&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>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 <code>media_files</code> 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 <code>path</code> and <code>title</code> value.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="c1"># The paths can be strings or pathlib Paths</span>
<span class="n">media_files</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;media/nla.news-article226799674-24144902.jpg&#39;</span><span class="p">]</span>

<span class="c1"># Include the media files when we upload the payload</span>
<span class="n">article_item</span> <span class="o">=</span> <span class="n">omeka_auth</span><span class="o">.</span><span class="n">add_item</span><span class="p">(</span><span class="n">article_payload</span><span class="p">,</span> <span class="n">media_files</span><span class="o">=</span><span class="n">media_files</span><span class="p">,</span> <span class="n">template_id</span><span class="o">=</span><span class="n">article_template_id</span><span class="p">)</span>
</pre></div>

    </div>
</div>
</div>

</div>
    {% endraw %}

<div class="cell border-box-sizing text_cell rendered"><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>When we look at the uploaded item, we'll see that the media files have been processed and added to the record.</p>

</div>
</div>
</div>
    {% raw %}
    
<div class="cell border-box-sizing code_cell rendered">
<div class="input">

<div class="inner_cell">
    <div class="input_area">
<div class=" highlight hl-ipython3"><pre><span></span><span class="n">article_item</span>
</pre></div>

    </div>
</div>
</div>

<div class="output_wrapper">
<div class="output">

<div class="output_area">



<div class="output_text output_subarea output_execute_result">
<pre>{&#39;@context&#39;: &#39;http://timsherratt.org/collections/api-context&#39;,
 &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/items/1046&#39;,
 &#39;@type&#39;: [&#39;o:Item&#39;, &#39;schema:NewsArticle&#39;],
 &#39;o:id&#39;: 1046,
 &#39;o:is_public&#39;: True,
 &#39;o:owner&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/users/1&#39;,
  &#39;o:id&#39;: 1},
 &#39;o:resource_class&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/resource_classes/543&#39;,
  &#39;o:id&#39;: 543},
 &#39;o:resource_template&#39;: {&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/resource_templates/4&#39;,
  &#39;o:id&#39;: 4},
 &#39;o:thumbnail&#39;: None,
 &#39;o:title&#39;: &#34;MR WRAGGE&#39;S PREDICTION. RENEWAL OF CYCLONE FORETOLD.&#34;,
 &#39;thumbnail_display_urls&#39;: {&#39;large&#39;: &#39;http://timsherratt.org/collections/files/large/c60918ee88cb729ae8803742bbbb185460700903.jpg&#39;,
  &#39;medium&#39;: &#39;http://timsherratt.org/collections/files/medium/c60918ee88cb729ae8803742bbbb185460700903.jpg&#39;,
  &#39;square&#39;: &#39;http://timsherratt.org/collections/files/square/c60918ee88cb729ae8803742bbbb185460700903.jpg&#39;},
 &#39;o:created&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:48:40+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:modified&#39;: {&#39;@value&#39;: &#39;2022-04-04T00:48:40+00:00&#39;,
  &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#dateTime&#39;},
 &#39;o:media&#39;: [{&#39;@id&#39;: &#39;http://timsherratt.org/collections/api/media/1047&#39;,
   &#39;o:id&#39;: 1047}],
 &#39;o:item_set&#39;: [],
 &#39;o:site&#39;: [],
 &#39;schema:name&#39;: [{&#39;type&#39;: &#39;literal&#39;,
   &#39;property_id&#39;: 1116,
   &#39;property_label&#39;: &#39;name&#39;,
   &#39;is_public&#39;: True,
   &#39;@value&#39;: &#34;MR WRAGGE&#39;S PREDICTION. RENEWAL OF CYCLONE FORETOLD.&#34;}],
 &#39;schema:datePublished&#39;: [{&#39;type&#39;: &#39;numeric:timestamp&#39;,
   &#39;property_id&#39;: 928,
   &#39;property_label&#39;: &#39;datePublished&#39;,
   &#39;is_public&#39;: True,
   &#39;@value&#39;: &#39;1918-03-14&#39;,
   &#39;@type&#39;: &#39;http://www.w3.org/2001/XMLSchema#date&#39;}],
 &#39;schema:isPartOf&#39;: [{&#39;type&#39;: &#39;resource:item&#39;,
   &#39;property_id&#39;: 736,
   &#39;property_label&#39;: &#39;isPartOf&#39;,
   &#39;is_public&#39;: True,
   &#39;@id&#39;: &#39;http://timsherratt.org/collections/api/items/1045&#39;,
   &#39;value_resource_id&#39;: 1045,
   &#39;value_resource_name&#39;: &#39;items&#39;,
   &#39;url&#39;: None,
   &#39;display_title&#39;: &#39;The Bendigo Independent (Vic. : 1891 - 1918)&#39;}],
 &#39;schema:url&#39;: [{&#39;type&#39;: &#39;uri&#39;,
   &#39;property_id&#39;: 393,
   &#39;property_label&#39;: &#39;url&#39;,
   &#39;is_public&#39;: True,
   &#39;@id&#39;: &#39;http://nla.gov.au/nla.news-article226799674&#39;}]}</pre>
</div>

</div>

</div>
</div>

</div>
    {% endraw %}

</div>