Explore the APIs

In the following links you can interact with the API for the different cities:

Delegation model

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.

delegation

API

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.

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:

  • version – the version of the hypermedia links.
  • _links – the resources available in the server, each with a given name shown in Resources.

Each of them are composed of:

    • href – the URI for the query;
    • templated – if set to true, the URI in href follows the URI Template RFC (e.g.: http://citysdk.com/v2/poi/search{?category,tag,complete,minimal,coords,show}).

Example:

http://tourism.citysdk.cm-lisboa.pt/resources

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:

1. find-poi

Description: Search Points of Interest using any of the given parameters.

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. The default value is 100, if you do not want any limit you can use limit=-1

Response: List of Points of Interest corresponding to the parameters.

Example:

http://tourism.citysdk.cm-lisboa.pt/pois/search?limit=10&offset=2
http://tourism.citysdk.cm-lisboa.pt/pois/search?category=Património - Monumentos Nacionais

2. find-poi-relations

Description: Search for Points of Interest related with another Point of Interest.

Parameters:

relation – it should be either child or parent

Response: List of Points of Interest related with a Point of Interest.

Example:

http://tourism.citysdk.cm-lisboa.pt/pois/52d7bf4d723e8e0b0cc08b5e/search?relation=child
http://tourism.citysdk.cm-lisboa.pt/pois/52d7bf4d723e8e0b0cc08b5e/search?relation=parent

3. find-event

Description: Search Events using any of the given parameters.

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.

Response: List of Events corresponding to the parameters.

Example:

http://tourism.citysdk.cm-lisboa.pt/events/search?category=Dstk-home-top&limit=2&offset=2
http://tourism.citysdk.cm-lisboa.pt/events/search?time=2014-05-20 2014-06-20

4. find-event-relations

Description: Search for Events related with another Event.

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.

Response: List of Routes corresponding to the parameters.

Example:

http://tourism.citysdk.cm-lisboa.pt/events/52d7bfe6723e8e0b0cc09c82/search?relation=child
http://tourism.citysdk.cm-lisboa.pt/events/52d7bfe6723e8e0b0cc09c82/search?relation=parent

5. find-route

Description: Search Routes using any of the given parameters.

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.

Response: List of Routes corresponding to the parameters.

Example:

http://tourism.citysdk.cm-lisboa.pt/routes/search?limit=-1

6. find-categories

Description: Search Categories for Points of Interest, Events or Routes.

Parameters:

list – it should be either poi, event or route;
limit and/or offset – filter the search to a set of results.

Response: List of Tags corresponding to requested list.

Example:

http://tourism.citysdk.cm-lisboa.pt/categories/search?list=poi&limit=10
http://tourism.citysdk.cm-lisboa.pt/categories/search?list=event&limit=10

7. find-tags

Description: Search Tags for Points of Interest, Events or Routes.

Parameters:

list – it should be either poi, event or route;
limit and/or offset – filter the search to a set of results.

Response: List of Tags corresponding to requested list.

8. find-code

Description: Search any given link for Points of Interest, Events or Routes.

Parameters:

code – the link that should be searched for.

Response: A list of lists: it may contain the 3 types in just one message.

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:

  • base – String – base URI of the POI;
  • id – String – the ID of the POI;
  • lang – String – the default language of the POI;
  • license – POITermType – the license restrictions of the POI;
    • term – String – to discreminate multiple licenses (e.g.: common, opensource);
    • value – String.
  • author – POITermType – the author of the POI;
    • term – String – to discreminate if the author is a primary, secondary, contributer, editor or publisher author;
    • value – String.
  • created – Date – the date in which the POI was created (format: YYYY-MM-DD’T’hh:mm:ss.SSSSSSS’Z’);
  • updated – Date – same format as created;
  • deleted – Date – same format as created;
  • label – POITermType – a human-readable name of the POI. Multiple names are used for synonyms and multiple languages;
    • lang – String – the language of the label;
    • term – String – if it is the primary or secondary name;
    • value – String.
  • description – POIBaseType – a human-readable description that can be discriminated with the language attribute;
    • lang – String;
    • value – String;
    • type – String – to discretize the type of description. Its values may be the following:
      • X-citysdk/price – containing, e.g., a price of entrance;
      • X-citysdk/waiting-time – indicating the waiting time in seconds;
      • X-citysdk/occupation – containing the occupation of the POI, between 0 and 100;
      • X-citysdk/accessibility-textual – accessibility information in human-readable format;
      • X-citysdk/accessibility-properties – containing machine-readable accessibility information.

      If this field is not present then, it is a description of the POI.

  • category – POITermType – categorical classification of the POI;
    • term – String – either a category or a tag;
    • value – String.
  • location – Location – provides information about the POI’s location;
      Contains 0 or more of the following geometries:
  • point;
    • Point – Geometry – a single point (latitude and longitude);
      • srsName – String – coordinate reference system;
      • posList – String – the coordinates set.
    • term – String – term used to describe this point. Recommended terms are: entrance, center, navigation point.
  • line;
    • LineString – Geometry – a set of two points;
      • srsName – String;
      • posList – String.
    • term – String – term used to describe this line.
  • polygon;
    • SimplePolygon – Geometry – a list of coordinates;
      • srsName – String;
      • posList – String.
    • term – String – term used to describe this polygon.
  • address – POIBaseType – the civic address of the POI;
    • type – String – text/vCard;
    • value – String – address in vCard format.
  • relationship- Relationship – establishes relations between POIs;
    • term – String – possible terms: equals, disjoint, intersects, crosses, overlaps, within, contains, touches;
    • base – String;
    • targetPOI – String – the ID of a Point of Interest; or targetEvent – String the ID of an Event.
  • time – POITermType – a fixed time or sequence of times using iCalendar;
    • term – String – possible terms: start, end, open and instant;
    • type – String – text/calendar;
    • value – String – the time in iCalendar format.
  • link – POITermType – a link to another POI or web resource;
    • term – String – possible terms: alternate, canonical, copyright, describedby, edit, enclosure, icon, latest-version, license, related, search, parent, child, historic and future;
    • type – String – the MIME type;
    • href – String – the absolute path of the link;
    • base – String;
    • id – String.

Examples1: Poi

http://tourism.citysdk.cm-lisboa.pt/pois/52d7bf92723e8e0b0cc0939f
{
  location: {
    point: [
      {
        Point: {
          posList: "38.6978420959093 -9.20648444262546",
          srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
        },
        term: "entrance"
      }
    ],
    address: {
      value: "BEGIN:VCARD VERSION:2.1 N:;Mosteiro dos Jerónimos;;;; ADR;WORK:;Praça do Império, Mosteiro; Rua dos Jerónimos, Mosteiro;;Lisboa;;;Portugal TEL;WORK: EMAIL;INTERNET: URL;WORK:http://www.mosteirojeronimos.pt END:VCARD ",
      type: "text/vcard"
    },
    relationship: [
      {
        targetPOI: "52d7bf4c723e8e0b0cc08b4f",
        term: "within",
        base: "http://tourism.citysdk.cm-lisboa.pt/pois/"
      }
    ]
  },
  label: [
    {
      term: "primary",
      value: "Mosteiro dos Jerónimos",
      lang: "pt-PT"
    },
    {
      term: "note",
      value: "Classificação como Monumento Nacional, pelos Decretos de 10-01-1907, DG n.º 14, de 17-01-1907 e de 16-06-1910, DG n.º 136, de 23-06-1910",
      lang: "pt-PT"
    }
  ],
  description: [
    {
      value: "Obra fundamental da arquitectura manuelina, está classificada como Monumento Nacional e inscrita, desde 1983, na lista de Património da Humanidade da UNESCO. Edificado por D. Manuel I como Panteão Real e Mosteiro da Ordem de S. Jerónimo, é também conhecido por Mosteiro de Sta. Maria de Belém. Iniciado em 1502 sob a direcção de Boitaca, seguiu-lhe João de Castilho a partir de 1517. A igreja, em cruz latina, tem 3 naves à mesma altura, divididas por pilares profusamente decorados, que sustentam a abóbada única polinervada. Destacam-se o portal principal, o portal da fachada sul de João de Castilho, a capela-mor maneirista de Jerónimo de Ruão, o claustro,a casa do capítulo e a tumulária. Objecto de profundas obras de restauro no séc. XIX, este complexo arquitectónico acolhe, ainda, o Museu da Marinha e o Museu Nacional de Arqueologia, no qual, entre outras, podemos observar duas peças classificadas como Monumento Nacional: a Lápide do Deus Esculápio e as Estátuas Lusitanas de Montalegre. ",
      lang: "pt-PT"
    }
  ],
  category: [
    {
      term: "category",
      value: "Unidade de Intervenção Territorial Ocidental",
      lang: "pt-PT"
    },
    {
      term: "category",
      value: "Património - Arquitectura Religiosa",
      lang: "pt-PT"
    },
    {
      term: "category",
      value: "Património - Monumentos Nacionais",
      lang: "pt-PT"
    }
  ],
  link: [
    {
      term: "related",
      href: "http://www.cm-lisboa.pt/uploads/pics/tt_address/lxi-2640-01.jpg",
      type: "image/png"
    },
    {
      term: "source",
      href: "http://www.mosteirojeronimos.pt",
      type: "text/html"
    },
    {
      term: "alternative",
      value: "http://www.mosteirojeronimos.pt"
    },
    {
      term: "related",
      href: "http://www.cm-lisboa.pt/uploads/pics/tt_address/lxi-2684-01.jpg",
      type: "image/png"
    }
  ],
  id: "52d7bf92723e8e0b0cc0939f",
  base: "http://tourism.citysdk.cm-lisboa.pt/pois/",
  lang: "pt-PT",
  created: "2013-10-02T03:00:05.0000000Z",
  author: {
    term: "primary",
    value: "CitySDK"
  },
  license: {
    term: "primary",
    value: "open-data"
  }
}

Examples2: Event

http://tourism.citysdk.cm-lisboa.pt/events/52d7bffc723e8e0b0cc0a1d6
{
  location: {
    point: [
      {
        Point: {
          posList: "38.713811 -9.139386",
          srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
        },
        term: "entrance"
      }
    ],
    relationship: [
      {
        targetPOI: "52d7bf4d723e8e0b0cc08b68",
        term: "within",
        base: "http://tourism.citysdk.cm-lisboa.pt/pois/"
      }
    ]
  },
  label: [
    {
      term: "primary",
      value: "São Luiz Teatro Municipal | Programa",
      lang: "pt-PT"
    },
    {
      term: "primary",
      value: "São Luiz Municipal Theatre | Programme",
      lang: "en-GB"
    }
  ],
  description: [
    {
      value: "A 22 de Maio de 1894 estreia um novo teatro em Lisboa. O Rei D. Carlos e a Rainha Dona Amélia, madrinha do novo espaço, estão presentes.
Durante décadas será palco de estreias que fizeram a história da sétima arte, com produções nacionais e estrangeiras e as maiores figuras do Teatro europeu da altura. A poesia, pela mão de Villaret, chega depois dos anos 50.
Em 1971, a Câmara Municipal de Lisboa adquire o Teatro, para dar início a uma série de temporadas, apresentadas por uma companhia residente, encabeçada por Eunice Muñoz e dirigida por Luiz Francisco Rebello. 
Na Sala Principal passaram nomes reconhecidos internacionalmente como Pina Bausch, Artur Pizarro, Maria João Pires, foram encenados autores como William Shakespeare, José Saramago, Federico Garcia Lorca, Sophia de Mello Breyner Andresen, tocaram grandes orquestras como a Orquestra Metropolitana de Lisboa, a Orquestra do Algarve, a Orquestra Sinfónica do Porto e a Jovem Orquestra Nacional de Espanha, cantaram grandes nomes do Fado como Camané, Cristina Branco, Mafalda Arnauth, Kátia Guerreiro, Argentina Santos, Celeste Rodrigues, Ricardo Ribeiro, Alcindo Carvalho, e tocaram nomes importantes do jazz nacional como Carlos Martins, Bernardo Sassetti, Mário Laginha e Maria João.   1 a 30 novembro",
      lang: "pt-PT"
    },
    {
      value: "On 22nd May 1894, the people of Lisbon assisted with great excitement at the opening of the new theatre, with the presence of His Majesty King Carlos and Her Majesty Queen Amelia.
For decades it hosted the premieres of major productions of the seventh art with foreign companies and major european actors. Poetry, by João Villaret, arrived only in the 50s.
In 1971, the Municipality of Lisbon purchased the building and presented a series of seasons with a new resident acting company, headed by Eunice Muñoz and managed by Luiz Francisco Rebelo. 
The Main Auditorium has received names with international credentials, such as Pina Bausch, Artur Pizarro, Maria João Pires,  it has hosted plays by William Shakespeare, José Saramago, Federico Garcia Lorca, Sophia de Mello Breyner Andresen, it has presented big orchestras such as Orquestra Metropolitana de Lisboa, Orquestra do Algarve, Orquestra Sinfónica do Porto and the Spanish National Youth Ochestra and the stage received big names of today´s fado, such as Camané, Cristina Branco, Mafalda Arnauth, Kátia Guerreiro, Argentina Santos, Celeste Rodrigues, Ricardo Ribeiro, Alcindo Carvalho and of the national jazz such as Carlos Martins, Bernardo Sassetti, Mário Laginha and Maria João. 
1 to 30 November",
      lang: "en-GB"
    }
  ],
  category: [
    {
      term: "category",
      value: "Informação local",
      lang: "pt-PT"
    }
  ],
  time: [
    {
      term: "open",
      value: "BEGIN:VCALENDAR VERSION:2.0 PRODID:-//ddaysoftware.com//NONSGML DDay.iCal 1.0//EN BEGIN:VEVENT DTEND:20140720T235900 DTSTART:20140210T000000 SEQUENCE:0 END:VEVENT END:VCALENDAR ",
      type: "text/icalendar"
    }
  ],
  link: [
    {
      term: "related",
      href: "http://www.cm-lisboa.pt/uploads/pics/saoluiz.jpg",
      type: "image/png"
    }
  ],
  id: "52d7bffc723e8e0b0cc0a1d6",
  base: "http://tourism.citysdk.cm-lisboa.pt/events/",
  lang: "pt-PT",
  created: "2013-10-31T15:06:29.0000000Z",
  author: {
    term: "primary",
    value: "Fernanda"
  },
  license: {
    term: "primary",
    value: "open-data"
  }
}

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:

  • The description field will only contain a description and no more data (such as prices or waiting time);
  • The location field will only contain a geometry describing its coordinates;
  • The links field will only contain a thumbnail and no other links relating to multimedia or alternative identifications.

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.

List of POIs, Events and Routes

You can specify the type of retrieved information, for example when searching for categories. Each of these elements have their own lists. The properties have the following names:

  • pois – will contain an array of Points of Interest in minimal description;
  • events – will contain an array of Events;
  • routes – will contain an array of Routes in minimal description.

There is also a special case (used by find-code resource or categories) 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:

  • label – having the same properties of the POI;
  • id – similar to POI;
  • term – similar to POI;
  • lang – similar to POI;
  • categories – to allow recursiveness and representing sub-categories of a given category.

Examples

http://tourism.citysdk.cm-lisboa.pt/categories/search?list=event&limit=3&offset=2
http://tourism.citysdk.cm-lisboa.pt/categories/search?list=poi&limit=5&offset=2

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:

  • lang – the language of the tag;
  • value – the actual tag name.

Directory Service

The directory service is available at http://directory.citysdk.cm-lisboa.pt/resources.

The CitySDK Tourism API was designed taking into account a delegation model. The directory service is the root of all the CitySDK Tourism endpoints. At this point the directory service has the partners endpoints: Amsterdam, Lamia, Lisbon and Rome.

discoveryservice

Examples1: Generic request

http://directory.citysdk.cm-lisboa.pt/resources
{
  citysdk-tourism: [
    {
      version: "1.0",
      _links: {
        find-poi: {
          href: "http://directory.citysdk.cm-lisboa.pt/pois/search{?category,tag,complete,minimal,coords,limit,offset}",
          templated: "true"
        },
        find-poi-relation: {
          href: "http://directory.citysdk.cm-lisboa.pt/pois/{id}/search{?relation}",
          templated: "true"
        },
        find-categories: {
          href: "http://directory.citysdk.cm-lisboa.pt/categories/search{?list,limit,offset}",
          templated: "true"
        },
        find-code: {
          href: "http://directory.citysdk.cm-lisboa.pt/search{?code}",
          templated: "true"
        }
      }
    }
  ]
}

Examples2: Search by coordinates

Searching for CitySDK Tourism endpoints by coordinates. In this example the coordinates are Latitude:38.723923 and Longitude:-9.135132. The coordinates correspond to the center of Lisbon.

http://directory.citysdk.cm-lisboa.pt/pois/search?coords=38.723923 -9.135132
{
  poi: [
    {
      location: {
        polygon: [
          {
            SimplePolygon: {
              posList: "...",
              srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
            },
            term: "entrance"
          }
        ]
      },
      label: [
        {
          term: "primary",
          value: "Lisbon",http://tourism.citysdk.cm-lisboa.pt/pois/search?limit=3&offset=10
          lang: "en-GB"
        }
      ],
      category: [
        {
          term: "category",
          value: "Directory Entries",
          lang: "en-GB"
        }
      ],
      link: [
        {
          term: "describedby",
          value: "http://tourism.citysdk.cm-lisboa.pt/resources"
        }
      ],
      id: "530947f0723e8e0cb410e1cd",
      base: "http://directory.citysdk.cm-lisboa.pt/pois/",
      created: "2014-02-23T00:59:28.0890000Z",
      author: {
        term: "primary",
        value: "admin"
      },
      license: {
        term: "primary",
        value: "CitySDK"
      }
    }
  ]
}

Examples3: List all the available endpoints

http://directory.citysdk.cm-lisboa.pt/pois/search?limit=-1
{
  poi: [
    {
      location: {
        polygon: [
          {
            SimplePolygon: {
              posList: "...",
              srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
            },
            term: "entrance"
          }
        ]
      },
      label: [
        {
          term: "primary",
          value: "Lisbon",
          lang: "en-GB"
        }
      ],
      category: [
        {
          term: "category",
          value: "Directory Entries",
          lang: "en-GB"
        }
      ],
      link: [
        {
          term: "describedby",
          value: "http://tourism.citysdk.cm-lisboa.pt/resources"
        }
      ],
      id: "530947f0723e8e0cb410e1cd",
      base: "http://directory.citysdk.cm-lisboa.pt/pois/",
      created: "2014-02-23T00:59:28.0890000Z",
      author: {
        term: "primary",
        value: "admin"
      },
      license: {
        term: "primary",
        value: "CitySDK"
      }
    },
    {
      location: {
        polygon: [
          {
            SimplePolygon: {
              posList: "52.4830 4.6259,52.4830 5.1450,52.2726 5.1450,52.2726 4.6259,52.4830 4.6259",
              srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
            },
            term: "entrance"
          }
        ]
      },
      label: [
        {
          term: "primary",
          value: "Amsterdam",
          lang: "en-GB"
        }
      ],
      category: [
        {
          term: "category",
          value: "Directory Entries",
          lang: "en-GB"
        }
      ],
      link: [
        {
          term: "describedby",
          value: "http://citysdk.dmci.hva.nl/CitySDK/resources"
        }
      ],
      id: "530947f1723e8e0cb410e1ce",
      base: "http://directory.citysdk.cm-lisboa.pt/pois/",
      created: "2014-02-23T00:59:29.0730000Z",
      author: {
        term: "primary",
        value: "admin"
      },
      license: {
        term: "primary",
        value: "CitySDK"
      }
    },
    {
      location: {
        polygon: [
          {
            SimplePolygon: {
              posList: "42.0251 12.2151,42.0251 12.7342,41.7685 12.7342,41.7685 12.2151,42.0251 12.2151",
              srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
            },
            term: "entrance"
          }
        ]
      },
      label: [
        {
          term: "primary",
          value: "Rome",
          lang: "en-GB"
        }
      ],
      category: [
        {
          term: "category",
          value: "Directory Entries",
          lang: "en-GB"
        }
      ],
      link: [
        {
          term: "describedby",
          value: "http://citysdk.inroma.roma.it/CitySDK/resources"
        }
      ],
      id: "530947f1723e8e0cb410e1cf",
      base: "http://directory.citysdk.cm-lisboa.pt/pois/",
      created: "2014-02-23T00:59:29.2290000Z",
      author: {
        term: "primary",
        value: "admin"
      },
      license: {
        term: "primary",
        value: "CitySDK"
      }
    },
    {
      location: {
        polygon: [
          {
            SimplePolygon: {
              posList: "39.0200 22.1975,39.0200 22.7166,38.7517 22.7166,38.7517 22.1975,39.0200 22.1975",
              srsName: "http://www.opengis.net/def/crs/EPSG/0/4326"
            },
            term: "entrance"
          }
        ]
      },
      label: [
        {
          term: "primary",
          value: "Lamia",
          lang: "en-GB"
        }
      ],
      category: [
        {
          term: "category",
          value: "Directory Entries",
          lang: "en-GB"
        }
      ],
      link: [
        {
          term: "describedby",
          value: "http://tourism.citysdk.lamia-city.gr/resources"
        }
      ],
      id: "530947f1723e8e0cb410e1d0",
      base: "http://directory.citysdk.cm-lisboa.pt/pois/",
      created: "2014-02-23T00:59:29.3860000Z",
      author: {
        term: "primary",
        value: "admin"
      },
      license: {
        term: "primary",
        value: "CitySDK"
      }
    }
  ]
}