{% extends "_page.html" %}

{% block body %}

<h1>{% block section_title_plural %}{% endblock %} Query</h1>

<p class="code">
    <strong>GET</strong> {% block section_get_url %}{% endblock %}<br/>
    <strong>POST</strong> {% block section_post_url %}{% endblock %}
</p>

{% block section_introduction %}{% endblock %}

<p>The HTTP GET request method is the preferred access mechanism; however when the query parameters exceed a reasonable size (around 2,000 characters), then the POST method can be used. When using the POST method, the query parameters should be embedded within a JSON string within the request body.</p>

<table class="table table-striped documentation-parameters">
    <thead>
        <tr>
            <th class="col-md-1">Name</th>
            <th class="col-md-6">Description</th>
            <th class="col-md-5">Details</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td class="code">q</td>
            <td>JSON formatted object containing the query parameters. See below for details on formatting this object.</td>
            <td>string, required <br/> <strong>example:</strong> <span class="code">{% block section_query_example %}{% endblock %}</span></td>
        </tr>
        <tr>
            <td class="code">f</td>
            <td>JSON formatted array of fields to include in the results. If not provided, defaults to {% block section_field_defaults %}{% endblock %}.</td>
            <td>string, optional <br/> <strong>example:</strong> <span class="code">{% block section_field_example %}{% endblock %}</span></td>
        </tr>
        <tr>
            <td class="code">s</td>
            <td>JSON formatted array of objects to sort the results. If not provided, defaults to <span class="code">{% block section_sort_default %}{% endblock %}</span>.</td>
            <td>string, optional <br/> <strong>example:</strong> <span class="code">{% block section_sort_example %}{% endblock %}</span></td>
        </tr>
        <tr>
            <td class="code">o</td>
            <td>
                <p>JSON formatted object of options to modify the query or results. Available options are:</p>
                <p><span class="code">matched_subentities_only</span> &mdash; Only subentity data that matches the subentity specific criteria is included in results. Defaults to true.</p>
                <p><span class="code">include_subentity_total_counts</span> &mdash; Total counts of unique subentities included in results. Defaults to false.</p>
                <p><span class="code">page</span> &mdash; return only the Nth page of results. Defaults to 1.</p>
                <p><span class="code">per_page</span> &mdash; Size of each page of results. Defaults to 25.</p>
            </td>
            <td>string, optional <br/> <strong>example:</strong> <span class="code">o={"matched_subentities_only": "true", "page": 2, "per_page": 50, "include_subentity_total_counts": "false"}</span></td>
        </tr>
        <tr>
            <td class="code">format</td>
            <td>
                <p>Specifies the response data format. If not provided, defaults to JSON. Available options are:</p>
                <p><span class="code">json</span></p>
                <p><span class="code">xml</span></p>
            </td>
            <td>string, optional <br/> <strong>example:</strong> <span class="code">format=xml</span></td>
        </tr>
    </tbody>
</table>

<p>An example of a complete API call using the GET verb is:</p>

<p class="well code"><a href='{{ base_url }}{{ self.section_get_url_example() | trim }}'>{{ base_url }}{% block section_get_url_example %}{% endblock %}</a></p>

<p>An example of the equivalent API call using the POST verb is:</p>

<p class="well code">{{ base_url }}{% block section_post_url_example %}{% endblock %}</p>

<p>with the body containing:</p>

<p class="well code">{% block section_post_body_example %}{% endblock %}</p>

<h2><a class="anchor"></a>Examples</h2>

{% block section_examples %}{% endblock %}

<h2><a class="anchor" name="field_list"></a>{{ self.section_title() }} Field List</h2>

<table class="table table-striped documentation-fieldlist">
    <tr>
        {% for name in field_list_column_names %}
        <th>{{name}}</th>
        {% endfor %}
    </tr>

    {% for field in field_list %}
    <tr>
        {% for name in field_list_column_names %}
        <td>{{ field[name] }}</td>
        {% endfor %}
    </tr>
    {% endfor %}
</table>

{% endblock %}