Search Locations
https://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
https://api.eventfinda.co.nz/v2/locations.xml?rows=2&offset=3&q=bar&venue=on
Example Response
<?xml version="1.0"?>
<error>An error occurred</error>
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
A side effect of specifying |
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
If nothing is specified locations are sorted by tree order with the root first. |
point |
In the format latitude,longitude
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
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.
https://api.eventfinda.co.nz/v2/locations.xml?rows=1&levels=2&fields=location:(id,url_slug,name,children)
Response
<?xml version="1.0"?>
<error>An error occurred</error>
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
"Virtual" which you can see from the above response
has the id
of 34045.
https://api.eventfinda.co.nz/v2/locations.xml?id=34045&levels=2&fields=location:(id,url_slug,name,children)
Response
<?xml version="1.0"?>
<error>An error occurred</error>
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 "virtual".
https://api.eventfinda.co.nz/v2/locations.xml?q=virtual&venue=off&fields=location:(id,url_slug,name,children)
Response
<?xml version="1.0"?>
<error>An error occurred</error>
By changing the venue=off
to venue=on
and adding
the location=34045
parameter you can then search for venues containing
"bar" in "Virtual".
https://api.eventfinda.co.nz/v2/locations.xml?q=bar&location=34045&venue=on&fields=location:(id,url_slug,name,children)
Response
<?xml version="1.0"?>
<error>An error occurred</error>