REST API

Main Entry Point

The CitySDK Tourism API is a RESTful API, since it follows a hypermedia-driven approach. So, performing a GET to the main URL will get you going through the system.

API Resources

In this section, you will find a description of the resources that you can access through the API.

Message Codes

In case of a successful request, a 2xx HTTP code will be returned alongside with the JSON response containing the results.

In case of an error - whether it be an erroneous request or a server-side error - the server will return a message containing a description of what went wrong. Alongside this description, a 5xx HTTP code will be returned.

Server Resources

Upon making the to the main URL, you will be presented with the server resources in various versions, indicating which queries are available in the visited server. The server resources is merely an array of of hypermedia links, where each element has the following properties:

To make a given query, simply use or build (if it is templated) the href of a given resource and perform a GET on the resulting URL.

[+] Resources
Resource Description Possible Parameters Response
find-poi Search Points of Interest using any of the given parameters.
  • category - search using categories;
  • tag - search using tags;
  • complete - search using keyword and get the complete description of the POIs;
  • minimal - search using keyword and get the minimal description of the POIs;
  • coords - search using coordinates. If it is a single point, the format is: [lat,lon,radius]. If it is multiple points, the format is [lat lon, lat lon];
  • limit and/or offset - filter the search to a set of results.
List of Points of Interest corresponding to the parameters.
Examples:

http://citysdk.com/v1/poi/search?category=sports

http://citysdk.com/v2/poi/search?category=sports&limit=10&offset=2&minimal=lisbon

find-poi-relations Search for Points of Interest related with another Point of Interest.
  • relation - it should be either child or parent
List of Points of Interest related with a Point of Interest.
Examples:

http://citysdk.com/v1/poi/5177f154c0eb8f1d4c79d4b4/search?relation=child

find-event Search Events using any of the given parameters.
  • category - search using categories;
  • tag - search using tags;
  • name - search using keyword;
  • coords - search using coordinates. Same format as Points of Interest;
  • time - search using time. It should specify a start and end date. The format is: YYYY-MM-DD[HH-mm-ss];
  • limit and/or offset - filter the search to a set of results.
List of Events corresponding to the parameters.
Examples:

http://citysdk.com/v1/event/search?time=2013-03-03%202013-03-06

http://citysdk.com/v2/event/search?category=sports&limit=10&offset=2&name=football

find-event-relations Search for Events related with another Event.
  • relation - it should be either child or parent
List of Events related with an Event.
Examples:

http://citysdk.com/v1/event/5177f154c0eb8f1d4c79d4b4/search?relation=child

find-route Search Routes using any of the given parameters.
  • category - search using categories;
  • tag - search using tags;
  • name - search using keyword;
  • coords - search using coordinates. Same format as Routes;
  • limit and/or offset - filter the search to a set of results.
List of Routes corresponding to the parameters.
Examples:

http://citysdk.com/v1/route/search?tag=music

http://citysdk.com/v2/route/search?category=culture&limit=10&offset=2

find-categories Search Categories for Points of Interest, Events or Routes.
  • list - it should be either poi, event or route;
  • limit and/or offset - filter the search to a set of results.
List of Categories corresponding to requested list.
Examples:

http://citysdk.com/v1/category/search?list=poi&limit=10&offset=2

find-tags Search Tags for Points of Interest, Events or Routes.
  • list - it should be either poi, event or route;
  • limit and/or offset - filter the search to a set of results.
List of Tags corresponding to requested list.
Examples:

http://citysdk.com/v1/tag/search?list=poi&limit=10&offset=2

find-code Search any given link for Points of Interest, Events or Routes.
  • code - the link that should be searched for.
A list of lists: it may contain the 3 types in just one message.
Examples:

http://citysdk.com/v1/search?code=www.some-link.com

[+] Resources JSON Example

Points Of Interest, Events and Routes

Each of the 3 resources follow the UML below. For further details go to W3C-POI WG. Since the 3 resources inherit from the POI class, its properties are as follows:

[+] POI JSON Example
								
							
[+] Event JSON Example
								
							

There is however some minimizations in the format for Points of Interest and Routes. The differences of the Points of Interest format reside in the following:

Routes is a special case of a POI, that is, it contains in its properties a list of Points of Interest with minimal description. So, alongside the presented properties (except for location and time), it contains an extra one called pois.

So, and just like the Points of Interest, Routes also has a minimal description. Such description will not contain the pois property.

Lists of Points Of Interest, Events and Routes

Each of these elements have their own lists. The properties have the following names:

There is also a special case (used by find-code resource) in which the 3 types of lists coexist. Its format is simply a JSON Object containing the 3 aforementioned names, if such search returns values for each of the 3 types.

Categories

The Categories (not to be mistaken with the category property) represents the available categories in a given server. Its properties have a recursive nature since a Category can contain itself. So, the Categories are represented as an array of categories with the following properties:

[+] Categories JSON Example
								
							

Tags

The Tags represent the available tags in a given server. It is an array of tag with the name tags. Each tag is an array of two properties:

[+] Tags JSON Example
								
							

Delegation model

As described before, the link field in a POI may contain the term described-by. This term and its corresponding href allows an application to fetch more granular data from other data sources. As such and as shown in the following diagram, one can travel from a world-wide directory (which provides a POI of a city) and from there, receive data about a POI, Event or Itinerary. These data models can further be described by more specific servers and their endpoints are provided by the described-by term.