api-docs

<div class="yui-ge">
  <div class="yui-u first">
    <% $toc->html_for_document_body( $m->request_comp()->name() ) | n %>
  </div>
  <div class="yui-u toc">
    <h2>Table of Contents</h2>

    <% $toc->html_for_toc() | n %>
  </div>
</div>

<%init>
my $docs = $m->scomp('.docs');

my $toc = Text::TOC::HTML->new();
$toc->add_file(
    file    => $m->request_comp()->name(),
    content => $docs,
);
</%init>

<%def .docs>
<p>
  VegGuide currently supports a read-only REST API. This API allows you to
  retrieve information about entries, regions, and users using a well-defined
  set of URIs. Currently, all information is returned as JSON.
</p>

<h2>Versioning</h2>

<p>
  This document describes version <strong>0.0.1</strong> of the VegGuide REST
  API. This version number follows the <a href="http://semver.org/">Semantic
  Versioning Specification</a>. Since the major version number is
  currently <strong>0</strong>, the API is still in the experimental phase,
  and may change a fair bit before it is declared stable.
</p>

<p>
  A new URI endpoint is considered a minor version change. Adding an
  additional key to an existing document is also a minor version
  change. Removing a key or changing an the type of an existing key in a
  document is a major version change. Removing a URI endpoint or changing it's
  document type entirely is a major version change.
</p>

<h2>Content Types</h2>

<p>
  All responses from this REST API are valid JSON documents. However, rather
  than using a generic <em>application/json</em> <strong>Content-Type</strong>
  header, we use a content type that specifies the data in the response.
</p>

<p>
  For example, information about an entry is returned with the content
  type <em style="white-space:nowrap">application/vnd.vegguide.org-entry+json;
  charset=UTF-8; version=1.0.0</em>. The first part of the content type tells
  you that the document contains information on a single entry. The rest
  indicates the charset and version.
</p>

<p>
  In the future, the minor and patch numbers of the version may change without
  warning. If we ever need to update the major version number, we will almost
  certainly honor the <strong>Accept</strong> header if it requests an older
  (major) version number.
</p>

<p>
  Each document describes either a single resource or a collection of
  resources. Typically, these resources will be regions, entries, or
  users. Depending on the document type, a resource may in turn contain
  information about related resources. For example, a region resource may
  include information about the entries it contains, or an entry may contain
  information about the user who created it.
</p>

<h2>Core Data Structures</h2>

<p>
  The follow data types appear in many responses, and the documentation will
  reference them rather than repeat their definitions over and over. Whenever
  a data structure includes a URI, that URI will contain the full URI,
  including scheme and hostname. The core data structures are always a JSON
  object with a set of well-defined keys and values.
</p>

<p>
  Some structures include both English data and localized data. The English
  data should always be in the Latin-1 subset of Unicode. The localized data
  may be in any script. In most cases, you can figure out the language of the
  localized data by looking at the locale associated with the region. All
  strings are in UTF-8 encoding.
</p>

<p>
  If a key's value would be null, an empty string, or an empty array, it is
  always omitted.
</p>

<p>
  All datetimes are
  returned <a href="http://tools.ietf.org/html/rfc3339">RFC3339</a>
  format. Datetimes are always in the UTC time zone.
</p>

<a name="Region"></a>
<h3>Region</h3>

<p>
  A region can be anything from a continent to a city. We also have some
  special regions like "Internet", "Airports", or a specific airport like "MSP
  - Twin Cities".
</p>

<p>
  A region can contain entries, child regions, or in some rare cases, both. A
  region data structure contains the following keys:
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>name</td>
      <td>string</td>
      <td>The name of the region in English.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>localized_name</td>
      <td>string</td>
      <td>The name of the region in the region's locale, if it has one.</td>
      <td></td>
    </tr>
    <tr>
      <td>is_country</td>
      <td>boolean</td>
      <td>Indicates whether or not the region is a country.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>locale</td>
      <td>string</td>
      <td>
        A locale code like "en_CA" or "zh_TW". This is the locale for any
        localized data associated with the region's entries. Elements of the
        locale code are separated by underscores ("_").
      </td>
      <td></td>
    </tr>
    <tr>
      <td>time_zone</td>
      <td>string</td>
      <td>
        The name of the time zone associated with this region. This will be an
        <a href="http://www.iana.org/time-zones/">IANA time zone</a> name like
        "America/Chicago" or "Asia/Taipei".
      </td>
      <td></td>
    </tr>
    <tr>
      <td>entry_count</td>
      <td>integer&nbsp;(>=&nbsp;0)</td>
      <td>
        The number of entries in the region. This only include entries which
        are not marked closed. Also note that this does not recurse into the
        child regions for this region. This may be 0.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>uri</td>
      <td>URI</td>
      <td>
        The canonical URI for the region. This URI always returns the full
        region data structure for the given region.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>entries_uri</td>
      <td>URI</td>
      <td>
        A URI which returns the list of entries for the region.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td colspan="4">
        <strong>The following keys are only present when the data structure
        includes related data.</strong>
      </td>
    </tr>
    <tr>
      <td>parent</td>
      <td><a href="#Region">Region</a></td>
      <td>
        The region's parent region, if it has one. This is a
        single <a href="#Region">Region</a> data structure without any related
        data. It may not be present if the region is a top-level region.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>children</td>
      <td>array of <a href="#Region">Regions</a></td>
      <td>
        An array of child regions contained in this region. For example, the
        "USA" region contains the "Minnesota" and "New York" regions, among
        others. The child regions are themselves Region data structures, but
        they do not include any related data. This key may not be present if
        the region does not have any child regions.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>comments</td>
      <td>array of <a href="#Comment">Comments</a></td>
      <td>
        An array of comment data structures. Comments for a region typically
        contain some information about veg eating in the region. They may also
        contain references to other websites of interest for the region. See
        below for details on the <a href="#Comment">Comment data
        structure</a>. This key may not be present if the region does not have
        any comments.
      </td>
      <td></td>
    </tr>
  </tbody>
</table>

<h3>Entry</h3>

<p>
  An entry is a single place in the database, such as a restaurant or grocery.
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>name</td>
      <td>string</td>
      <td>The entry's name in English.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>distance</td>
      <td>string</td>
      <td>
        The entry's distance from a search location. This is only present when
        searching for entries near a specific location. The string will
        include a number and units, something like "1.3 miles".
      </td>
      <td>
        This is always present for entries in geographical search results,
        and never present otherwise.
      </td>
    </tr>
    <tr>
      <td>sortable_name</td>
      <td>string</td>
      <td>
        The entry's name in English, but with words like "A" and "The"
        removed. This is only done for English words.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>localized_name</td>
      <td>string</td>
      <td>The name of the entry in the language of region's locale, if it has one.</td>
      <td></td>
    </tr>
    <tr>
      <td>short_description</td>
      <td>string</td>
      <td>A short description of the entry.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>localized_short_description</td>
      <td>string</td>
      <td>A short description in the language of the region's locale.</td>
      <td></td>
    </tr>
    <tr>
      <td>long_description</td>
      <td><a href="#Formatted-Text">Formatted Text</a></td>
      <td>
        A longer description of the entry. This may
        include <a href="#wikitext">VegGuide wikitext markup</a>.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>localized_long_description</td>
      <td><a href="Formatted-Text">Formatted Text</a></td>
      <td>
        A long description in the language of the region's locale. This may
        include <a href="#wikitext">VegGuide wikitext markup</a>.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>
        address1,<br />
        address2,<br />
        neighborhood,<br />
        city,<br />
        region,<br />
        postal_code
      </td>
      <td>string</td>
      <td>
        Address information for the entry. The <code>region</code> is the
        entry's state or province.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>
        localized_address1,<br />
        localized_address2,<br />
        localized_neighborhood,<br />
        localized_city,<br />
        localized_region,<br />
        postal_code
      </td>
      <td>string</td>
      <td>Localized address information for the entry.</td>
      <td></td>
    </tr>
    <tr>
      <td>directions</td>
      <td>string</td>
      <td>Directions to the location of the entry.</td>
      <td></td>
    </tr>
    <tr>
      <td>phone</td>
      <td>string</td>
      <td>
        A phone number for the entry. This will not be in any specific format,
        and may not always include a country prefix.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>website</td>
      <td>URI</td>
      <td>
        A website for the entry. This may be a Facebook page in some cases.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>
        veg_level,<br />
        veg_level_description
      </td>
      <td>
        integer,<br />
        string
      </td>
      <td>
        <p>
          How veg-friendly the entry is, from 0-5. The levels are:
        </p>

        <ul>
% for my $level (0..5) {
          <li><strong><% $level %></strong> - <% VegGuide::Vendor->VegLevelDescription($level) %></li>
% }
        </ul>

        <p>
          Level 0 and level 3 are both very rare in our database.
        </p>
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>price_range</td>
      <td>string</td>
      <td>
        <p>
          A description of the entry's price range. Currently these can be:
        </p>

        <ul>
% for my $pr ( VegGuide::PriceRange->All() ) {
          <li><% $pr->description() %></li>
% }
        </ul>
      </td>
      <td></td>
    </tr>
    <tr>
      <td>hours</td>
      <td>array of objects</td>
      <td>
        <p>
          This key describes the entry's hours of operations. It consists of
          an array of objects. Each objects has two keys, <code>days</code>
          and <code>hours</code>. The <code>days</code> key contains something
          like "Mon" or "Mon - Fri". The <code>hours</code> key is itself an
          array of strings. Each element of the array contains a time
          range. Some places close between lunch and dinner, and these have
          two elements in the array. There is an example at the end of this
          table.
        </p>
      </td>
      <td></td>
    </tr>
    <tr>
      <td>allows_smoking</td>
      <td>boolean or null</td>
      <td>
        Indicates whether or not smoking is allows at this place. Note that
        this field can be <code>null</code>, which means that we do not know
        whether or not smoking is allowed.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>is_wheelchair_accessible</td>
      <td>boolean or null</td>
      <td>
        A boolean indicating whether or not this entry is
        wheelchair-accessible. This field can be <code>null</code>, which
        means that we do not know whether or not it is accessible.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>accepts_reservations</td>
      <td>boolean or null</td>
      <td>
        A boolean indicating whether or not this entry accepts
        reservations. This field can be <code>null</code>, which means that we
        do not know whether or not it accepts reservations.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>is_cash_only</td>
      <td>boolean</td>
      <td>Indicates whether or not this entry only accepts cash as payment.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>
        creation_datetime,<br />
        last_modified_datetime
      </td>
      <td>datetime</td>
      <td>
        When an entry is first created, these two datetimes are the same.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>close_date</td>
      <td>date</td>
      <td>
        This is set when an entry is no longer open. This is just a date
        with a time in YYYY-MM-DD format, something like "2012-07-09".
      </td>
      <td></td>
    </tr>
    <tr>
      <td>rating_count</td>
      <td>integer&nbsp;(>=&nbsp;0)</td>
      <td>
        The number of ratings for this entry. This may be 0.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>weighted_rating</td>
      <td>decimal</td>
      <td>
        The weighted rating for the entry. This will be a decimal number from
        1 to 5. This will not be present if no one has rated the entry yet.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>categories</td>
      <td>array of strings</td>
      <td>
        <p>
          An array of category names for the entry. Every entry has at least
          one category. The current list of categories is:
        </p>

        <ul>
% for my $category ( VegGuide::Category->All() ) {
          <li><% $category->name() %></li>
% }
        </ul>
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>cuisines</td>
      <td>array of strings</td>
      <td>
        <p>
          An array of cuisines names for the entry. These are things like
          "Chinese", "Indian", or "Pizza". This only applies to some
          categories of entry, and not every entry has this key set. These are
          always returned in alphabetically sorted order.
        </p>
      </td>
      <td></td>
    </tr>
    <tr>
      <td>tags</td>
      <td>array of strings</td>
      <td>
        <p>
          An array of tags for the entry. These are things like "Large
          Group-Friendly" or "Romantic". These are returned in alphabetically
          sorted order.
        </p>
      </td>
      <td></td>
    </tr>
    <tr>
      <td>images</td>
      <td>array of <a href="#Image">Images</a></td>
      <td>
        An array of <a href="#Image">Image data structures</a> for the
        entry. Each image will include four sizes. The first three are limited
        to 120x120, 250x250, and 400x620 respectively. The last will be the
        image that was originally uploaded, which can be any size, and may
        potentially be quite large.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>user</td>
      <td><a href="#User">User</a></td>
      <td>
        A <a href="#User">User data structure</a> for the creator of this
        entry. This data structure <em>does not</em> include related data.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>uri</td>
      <td>URI</td>
      <td>
        The canonical URI for the entry. This URI always returns the full
        entry data structure for the given entry.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>reviews_uri</td>
      <td>URI</td>
      <td>
        A URI which returns the reviews and ratings for this entry.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td colspan="4">
        <strong>The following keys are only present when the data structure
        includes related data.</strong>
      </td>
    </tr>
    <tr>
      <td>region</td>
      <td><a href="#Region">Region</a></td>
      <td>
        A <a href="#Region">Region</a> data structure for the creator of this
        entry. This data structure <em>does not</em> include related data.
      </td>
      <td>&#x2714; (when related data is included)</td>
    </tr>
  </tbody>
</table>

<p>
  Here is an example of the hours data structure:
</p>

<pre><code>[
    {
        days  => 'Mon - Fri',
        hours => ['10:30am - 2pm', '5pm - 10pm']
    },
    {
        days  => 'Sat - Sun',
        hours => ['closed']
    }
]</code></pre>

<a name="User"></a>
<h3>User</h3>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>name</td>
      <td>string</td>
      <td>The user's username.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>bio</td>
      <td><a href="Formatted-Text">Formatted Text</a></td>
      <td>
        Biographical information about the user.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>
        veg_level,<br />
        veg_level_description
      </td>
      <td>
        integer,<br />
        string
      </td>
      <td>
        <p>
          How vegetarian the user is, from 0-4. The levels are:
        </p>


        <ul>
% for my $level (0..4) {
          <li><strong><% $level %></strong> - <% VegGuide::User->VegLevelDescription($level) %></li>
% }
        </ul>
      </td>
      <td></td>
    </tr>
    <tr>
      <td>website</td>
      <td>URI</td>
      <td>
        The website for the user.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>image</td>
      <td><a href="#Image">Image</a></td>
      <td>
        An <a href="#Image">Image data structure</a> for the user. This will
        include two sizes of image. The smaller of the two is limited to
        40x40, and the larger to 100x100. The image data structure will not
        include user information, since it is always the same to whom the
        image belongs.
      </td>
      <td></td>
    </tr>
    <tr>
      <td>uri</td>
      <td>URI</td>
      <td>
        The canonical URI for the user. This URI always returns the full user
        data structure for the given user.
      </td>
      <td>&#x2714;</td>
    </tr>
  </tbody>
</table>

<a name="Comment"></a>
<h3>Comment</h3>

<p>
  Both region comments and entry reviews are returned with essentially the
  same data structure, though reviews have some additional data.
</p>

<p>
  Note that an entry review may contain just a body, just a rating, or both.
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>body</td>
      <td><a href="#Formatted-Text">Formatted Text</a></td>
      <td>
        The comment body as a <a href="#Formatted-Text">Formatted Text data
        structure</a>.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>user</td>
      <td><a href="#User">User</a></td>
      <td>
        A <a href="#User">User data structure</a> for the author of the
        comment. This data structure <em>does not</em> include related data.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>
        last_modified_datetime
      </td>
      <td>datetime</td>
      <td>
        When this comment was created or most recently updated.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>rating</td>
      <td>integer (1-5)</td>
      <td>
        A rating from 1 to 5, where 1 is terrible and 5 is excellent. This is
        only present for entry reviews, not region comments.
      </td>
      <td></td>
    </tr>
  </tbody>
</table>

<a name="Image"></a>
<h3>Image</h3>

<p>
  An image is a single picture, usually available in multiple sizes. The image
  data may include a caption, as well as information about the user who
  uploaded the image.
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>mime_type</td>
      <td>string</td>
      <td>
        This will be one of <em>image/gif</em>, <em>image/jpeg</em>,
        or <em>image/png</em>.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>caption</td>
      <td>string</td>
      <td>A caption for the image.</td>
      <td></td>
    </tr>
    <tr>
      <td>files</td>
      <td>array of <a href="#Image-File">Image Files</a></td>
      <td>
        This is an array of image file structures. Each structure provides
        information about an image file with a specified size. The array is
        always sorted by size. The possible dimensions for each image file
        depends on whether this is a user or entry image.
      </td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>user</td>
      <td><a href="#User">User</a></td>
      <td>
        A <a href="#User">User data structure</a> for the creator of this
        entry. This data structure <em>does not</em> include related data.
      </td>
      <td></td>
    </tr>
  </tbody>
</table>

<a name="Image-File"></a>
<h3>Image File</h3>

<p>
  This data structure contains information about a specific file for an image.
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Description</th>
      <th>Always present?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>uri</td>
      <td>URI</td>
      <td>The URI for this image file.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>height</td>
      <td>positive integer</td>
      <td>The height of the image.</td>
      <td>&#x2714;</td>
    </tr>
    <tr>
      <td>width</td>
      <td>positive integer</td>
      <td>The width of the image.</td>
      <td>&#x2714;</td>
    </tr>
  </tbody>
</table>

<a name="Formatted-Text"></a>
<h3>Formatted Text</h3>

<p>
  Some fields contain a type of wikitext which is rendered as HTML on the
  website. These fields are returned as objects where the attribute names are
  a MIME type and the attribute values are the text in that format. Currently,
  this data structure return two MIME types, <em>text/html</em>,
  and <em style="white-space:nowrap">text/vnd.vegguide.org-wikitext</em>. The
  wikitext format VegGuide uses
  is <a href="/site/help#wiki-formatting">described on the help page</a>.
</p>

<code><pre>
    {
        'text/html':                      '&lt;p&gt;Blah blah blah&lt;/p&gt;',
        'text/vnd.vegguide.org-wikitext': 'Blah blah blah'
    }
</pre></code>

<p>
  In the future, the site will use Markdown internally, and the existing
  wikitext format will go away. You are encouraged to use the HTML
  representation if you can.
</p>

<h2>Entry Points</h2>

<p>
  The VegGuide REST API defines several well known entry points. These URIs
  are guaranteed to exist, and their responses will generally contain links to
  other site URIs.
</p>

<p>
  Many of the URIs that the site offers include a numeric id, for
  example <code>/region/13</code>. You are strongly encouraged <em>not</em> to
  rely on the stability of these numbers. Instead, use one of the defined
  entry points to find items of interest for your applications.
</p>

<h3>Top-level</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-regions+json
  </li>
</ul>

<p>
  The top-level URI returns a document enumerating the top-level regions.
</p>

<p>
  The structure of the document is as follows:
</p>

<pre><code>{
    "regions": {
        "primary":   [ ... ],
        "secondary": [ ... ]
    }
}</code></pre>

<p>
  The primary and secondary keys contain an array of <a href="#Region">Region
  data structures</a> with related data. The primary regions are continents
  and oceanic areas. The secondary regions are currently just "Internet" and
  "Airports".
</p>

<h3>Geographical Searches</h3>

<p>
  There are two different entry point URIs for geographical searches. You can
  search by address or by latitude and longitude. Both URIs return the same
  response.
</p>

<ul>
  <li>
    <strong>Address URI</strong>: <% $base_uri %>search/by-address/<code>{address}</code>
  </li>
  <li>
    <strong>Lat/Long URI</strong>: <% $base_uri %>search/by-lat-long/<code>{latitude}</code>,<code>{longitude}</code>
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-entries+json
  </li>
</ul>

<p>
  These searches accept the following query parameters:
</p>

<table class="docs-table">
  <thead>
    <tr>
      <th>Key name</th>
      <th>Type</th>
      <th>Default value</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>distance</td>
      <td>positive number</td>
      <td>5</td>
      <td>The search radius in miles or kilometers.</td>
    </tr>
    <tr>
      <td>unit</td>
      <td>enum</td>
      <td>see description</td>
      <td>
        This can be either <code>mile</code> or <code>km</code>. If the search
        is for an address in the US, this defaults to <code>mile</code>,
        otherwise it defaults to <code>km</code>.
      </td>
    </tr>
    <tr>
      <td>limit</td>
      <td>positive integer</td>
      <td>50</td>
      <td>
        The maximum number of entries to return. This cannot be greater than
        100.
      </td>
    </tr>
    <tr>
      <td>page</td>
      <td>positive integer</td>
      <td>1</td>
      <td>
        If there are more than <code>limit</code> entries in the search, this
        parameter lets you fetch subsequent pages of results.
      </td>
    </tr>
  </tbody>
</table>

<p>
  This document returns the result of a search around a specific address or
  latitude and longitude.
</p>

<pre><code>{
    "uri":         "http://...",
    "entry_count": 123,
    "entries":     [ ... ],
    "region":      { ... }
}</code></pre>

<p>
  The <em>entries</em> key contains an array of <a href="#Entry">Entry data
  structures</a> without related data. The entry data structures <em>will</em>
  include a <em>distance</em> key. The <em>regions</em> key contains the
  region associated with the nearest entry. This is a <a href="#Region">Region
  data structure</a> without related data.
</p>

<p>
  If you search by address and the address does not resolve to a latitude and
  longitude, we return a <a href="#Not-Found">404 Not Found</a> response.
</p>

<h2>Other URIs</h2>

<p>
  These URIs will show up in other data structures, so understanding their
  document structures is important when coding to this API. All of these URIs
  include a numeric id, and you are encouraged not to rely on these numbers
  remaining stable.
</p>

<h3>Region</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>region/<code>{id}</code>
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-region+json
  </li>
</ul>

<p>
  Returns a <a href="#Region">Region data structure</a>. These URIs show up in
  any response that includes region URIs, including the top level response, a
  region's list of child regions, and an entry's link to its containing
  region.
</p>

<h3>Region Entries</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>region/<code>{id}</code>/entries
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-entries+json
  </li>
</ul>

<p>
  Returns an array of <a href="#Region">Entry data structures</a>.
  region. This document only includes entries that are not marked as closed.
</p>

<h3>Entry</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>entry/<code>{id}</code>
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-entry+json
  </li>
</ul>

<p>
  Returns a <a href="#Entry">Entry data structure</a>. These URIs show up in
  any response that includes entry URIs, such as a region's entries list or
  search results.
</p>

<h3>Entry Reviews</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>entry/<code>{id}</code>/reviews
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-entry-reviews+json
  </li>
</ul>

<p>
  Returns an array of <a href="#Comment">Comment data structures</a>. These
  URIs show up in any response that includes entry review URIs, such as a
  entry's reviews list.
</p>

<h3>User</h3>

<ul>
  <li>
    <strong>URI</strong>: <% $base_uri %>user/<code>{id}</code>
  </li>
  <li>
    <strong>Type</strong>: application/vnd.vegguide.org-user+json
  </li>
</ul>

<p>
  Returns a <a href="#User">User data structure</a>. These URIs show up in any
  response that includes user URIs, such as an entry or image data structure.
</p>

<a name="Error-Responses"></a>
<h2>Error Responses</h2>

<p>
  Error responses are accompanied by a JSON document body describing the error
  except for errors in the 5xx range, which typically mean something went
  wrong server side. The content type for errors is
  always <em>application/vnd.vegguide.org-error+json</em>
</p>

<p>
  Error bodies are a JSON object containing one key, <code>error</code>. The
  value for this key is a user-readable message describing the error.
</p>

<%init>
my $uri = $c->request()->uri();

my %port = $uri->port() != 80
    && $uri->port() != 443 ? ( port => $uri->port() ) : ();

my $base_uri = uri(
    scheme => $uri->scheme(),
    host   => $uri->host(),
    %port,
);
</%init>
</%def>

<%method page_title>
VegGuide.org REST API
</%method>