Search Locations

http://api.eventfinda.co.nz/v2/locations.xml

Searches the database and returns locations and venues matching the given criteria.

Locations are in a tree structure which you can explore on the Find Events page.

You can also explore the location tree using the API which is explained in more detail in the exploring the location tree section below.

Example Request

http://api.eventfinda.co.nz/v2/locations.xml?rows=2&offset=3&q=bar&venue=on

Example Response

<?xml version="1.0"?>
<locations count="1774">
 <location>
  <id>29517</id>
  <name>Armadillos Bar</name>
  <summary>Armadillos Bar, Christchurch</summary>
  <url_slug>armadillos-bar-christchurch</url_slug>
  <is_venue>1</is_venue>
  <count_current_events>8</count_current_events>
  <url>https://www.eventfinda.co.nz/venue/armadillos-bar-christchurch</url>
  <description/>
  <images count="1">
   <image>
    <id/>
    <is_primary>1</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/images/global/iconVenue-2.png</url>
      <width>80</width>
      <height>80</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/images/global/iconVenue-15.png</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/images/global/iconVenue-8.png</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/images/global/iconVenue-27.png</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/images/global/iconVenue-7.png</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
  </images>
  <address>155 Colombo St, Christchurch</address>
  <point>
   <lat>-43.5566</lat>
   <lng>172.6365</lng>
  </point>
  <booking_web_site>
   <url/>
   <name>Buy Tickets</name>
  </booking_web_site>
  <booking_phone/>
  <is_free>0</is_free>
  <is_featured>0</is_featured>
  <restrictions>All Ages</restrictions>
  <ticket_types count="0"/>
  <contacts count="1">
   <contact>
    <name>Phone</name>
    <value>03 337 2233</value>
   </contact>
  </contacts>
  <amenities count="0"/>
  <hours count="0"/>
  <web_sites count="1">
   <web_site>
    <url>http://www.armadillosrestaurantsnz.com</url>
    <name>Armadillos Bar</name>
   </web_site>
  </web_sites>
 </location>
 <location>
  <id>4144</id>
  <name>Basement Bar</name>
  <summary>Basement Bar, Wellington</summary>
  <url_slug>the-basement-wellington</url_slug>
  <is_venue>1</is_venue>
  <count_current_events>7</count_current_events>
  <url>https://www.eventfinda.co.nz/venue/the-basement-wellington</url>
  <description><![CDATA[The Basement Bar has so ... n\'s only true Backpacker Bar.]]></description>
  <images count="8">
   <image>
    <id>692822</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692822-4144-2.jpg</url>
      <width>80</width>
      <height>45</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692822-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692822-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692822-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692822-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>692823</id>
    <is_primary>1</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692823-4144-2.jpg</url>
      <width>80</width>
      <height>45</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692823-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692823-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692823-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692823-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>692824</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692824-4144-2.jpg</url>
      <width>80</width>
      <height>45</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692824-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692824-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692824-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692824-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>692825</id>
    <is_primary>0</is_primary>
    <transforms count="3">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692825-4144-2.jpg</url>
      <width>80</width>
      <height>45</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692825-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692825-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>692826</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692826-4144-2.jpg</url>
      <width>80</width>
      <height>44</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692826-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692826-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692826-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692826-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>692827</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692827-4144-2.jpg</url>
      <width>80</width>
      <height>40</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692827-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692827-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/692827-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/692827-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>877189</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877189-4144-2.jpg</url>
      <width>80</width>
      <height>53</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/877189-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877189-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/877189-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877189-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
   <image>
    <id>877190</id>
    <is_primary>0</is_primary>
    <transforms count="5">
     <transform>
      <transformation_id>2</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877190-4144-2.jpg</url>
      <width>80</width>
      <height>67</height>
     </transform>
     <transform>
      <transformation_id>15</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/877190-4144-15.jpg</url>
      <width>75</width>
      <height>75</height>
     </transform>
     <transform>
      <transformation_id>8</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877190-4144-8.jpg</url>
      <width>190</width>
      <height>127</height>
     </transform>
     <transform>
      <transformation_id>27</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... ions/transformed/877190-4144-27.jpg</url>
      <width>350</width>
      <height>350</height>
     </transform>
     <transform>
      <transformation_id>7</transformation_id>
      <url>http://cdn.eventfinda.co.nz/uploads ... tions/transformed/877190-4144-7.jpg</url>
      <width>650</width>
      <height>280</height>
     </transform>
    </transforms>
   </image>
  </images>
  <address>21-23 Cambridge Terrace, Wellington</address>
  <point>
   <lat>-41.2947</lat>
   <lng>174.7831</lng>
  </point>
  <booking_web_site/>
  <booking_phone/>
  <is_free>1</is_free>
  <is_featured>0</is_featured>
  <restrictions>R18</restrictions>
  <ticket_types count="0"/>
  <contacts count="1">
   <contact>
    <name>Phone</name>
    <value>64 4 801 5666</value>
   </contact>
  </contacts>
  <amenities count="3">
   <amenity>
    <name>Wheelchair Access</name>
   </amenity>
   <amenity>
    <name>Toilets</name>
   </amenity>
   <amenity>
    <name>Food Available</name>
   </amenity>
  </amenities>
  <hours count="0"/>
  <web_sites count="1">
   <web_site>
    <url>http://www.facebook.com/wellingtonbar</url>
    <name>Basement Bar Appreciation Society</name>
   </web_site>
  </web_sites>
 </location>
</locations>

Parameters

The following parameters are available along with the common parameters.

featured

If set to 1, only return locations marked as featured.

levels

An integer specifying the number of child location levels to include in the children element of the returned results. For example specifying 1 (which is the default) would include only the matching locations without a children element. Specifying levels=2 would include the matching locations and their immediate children. Specifying levels=3 would include the matching locations, their immediate children and their immediate children's children.

A side effect of specifying levels greater than 1 is that the first level of locations will also have a parents element. The parents element includes a collection of location elements which are ancestors of the location with the more immediate ancestors first.

location

Only return locations which are a descendent of this location ID.

Specify multiple IDs by separating them with a comma (,).

location_slug

Only return locations where are a descendent of the location specified by this URL slug

Specify multiple URL slugs by separating them with a comma (,).

order

Specify the order the results should be in. Possible values are

  • popularity
  • distance (only available with the point parameter)

If nothing is specified locations are sorted by tree order with the root first.

point

In the format latitude,longitude

/locations.xml?point=-36.84846,174.763332&order=distance
This parameter only makes sense if you also specify the order and/or radius parameters.

radius

Only include events within the given kilometers of the given point

/locations.xml?point=-36.84846,174.763332&distance=5
Would only return events within 5 kilometers of the point. Fractions of a kilometer can also be specified.

venue

If this parameter is present and true then only locations which are venues are returned. If its present and false then venues are excluded

Exploring the Location Tree

Many of the other end points accept a location or location_slug parameter, for example the events end point allows filtering events within a specific location. To find out the id or slug of a location to use in the location or location_slug parameters you can look them up. There are a couple of techniques to do this. The first is to use the children field to explore down the location tree. For example here is how you would get the root location and it's children.

http://api.eventfinda.co.nz/v2/locations.xml?rows=1&levels=2&fields=location:(id,url_slug,name,children)

Response

<?xml version="1.0"?>
<locations count="25319">
 <location>
  <id>574</id>
  <name>New Zealand</name>
  <url_slug>new-zealand</url_slug>
  <children count="16">
   <location>
    <id>30779</id>
    <name>Feilding and District</name>
    <url_slug>fielding-and-districts</url_slug>
   </location>
   <location>
    <id>1</id>
    <name>Northland</name>
    <url_slug>northland</url_slug>
   </location>
   <location>
    <id>2</id>
    <name>Auckland</name>
    <url_slug>auckland</url_slug>
   </location>
   <location>
    <id>41</id>
    <name>The Coromandel</name>
    <url_slug>the-coromandel</url_slug>
   </location>
   <location>
    <id>6</id>
    <name><![CDATA[Hawke\'s Bay / Gisborne]]></name>
    <url_slug>hawkes-bay-gisborne</url_slug>
   </location>
   <location>
    <id>3</id>
    <name>Waikato</name>
    <url_slug>waikato</url_slug>
   </location>
   <location>
    <id>4</id>
    <name>Bay of Plenty</name>
    <url_slug>bay-of-plenty</url_slug>
   </location>
   <location>
    <id>7</id>
    <name>Taranaki</name>
    <url_slug>taranaki</url_slug>
   </location>
   <location>
    <id>9</id>
    <name>Manawatu / Whanganui</name>
    <url_slug>manawatu-wanganui</url_slug>
   </location>
   <location>
    <id>11</id>
    <name>Wellington Region</name>
    <url_slug>wellington-region</url_slug>
   </location>
   <location>
    <id>12</id>
    <name>Nelson / Tasman</name>
    <url_slug>nelson-tasman</url_slug>
   </location>
   <location>
    <id>13</id>
    <name>Marlborough</name>
    <url_slug>marlborough</url_slug>
   </location>
   <location>
    <id>14</id>
    <name>West Coast</name>
    <url_slug>west-coast</url_slug>
   </location>
   <location>
    <id>15</id>
    <name>Canterbury</name>
    <url_slug>canterbury</url_slug>
   </location>
   <location>
    <id>17</id>
    <name>Otago</name>
    <url_slug>otago</url_slug>
   </location>
   <location>
    <id>18</id>
    <name>Southland</name>
    <url_slug>southland</url_slug>
   </location>
  </children>
 </location>
</locations>

You can delve deeper into the tree structure by adding the id of a location whose children you want to see. In this case we'll look for the children of "Feilding and District" which you can see from the above response has the id of 30779.

http://api.eventfinda.co.nz/v2/locations.xml?id=30779&levels=2&fields=location:(id,url_slug,name,children)

Response

<?xml version="1.0"?>
<locations count="1">
 <location>
  <id>30779</id>
  <name>Feilding and District</name>
  <url_slug>fielding-and-districts</url_slug>
  <children count="0"/>
 </location>
</locations>

The second method is looking for specific locations or venues using the q parameter. For example this query will look for locations containing the term "feilding and district".

http://api.eventfinda.co.nz/v2/locations.xml?q=feilding and district&venue=off&fields=location:(id,url_slug,name,children)

Response

<?xml version="1.0"?>
<error>The given URL (http://api.eventfind ... children)) returns an error (400: )</error>

By changing the venue=off to venue=on and adding the location=30779 parameter you can then search for venues containing "bar" in "Feilding and District".

http://api.eventfinda.co.nz/v2/locations.xml?q=bar&location=30779&venue=on&fields=location:(id,url_slug,name,children)

Response

<?xml version="1.0"?>
<locations count="0"/>