UfoSeti API description

What API is for?

Application Programming Interface (API) is a specification intended to be used as an interface by software components to communicate with each other. UfoSeti presents own API for everyone, without any restrictions.

What it provides

UfoSeti provides an open access to the database for third parties. Service includes reading and writing to the database with POST request. Currently two formats are supported: JSON and XML. General statistics available as well.

Database status

UfoSeti API provides general information about current database status. For retrieveing the state information a following request is suppotered:

format - n expected output format. Possible options: JSON, XML. Default is: JSON.
countries - fulter messages with countryен codes. Expected format is ISO 3166-1 alpha-2 (two caracters code),all the codes should be listed with comma with no space. This parameter is optional and can be ignored.

JSON request for the general database status

Request

http://www.ufoseti.org/api/v1/messages/status.json

Responce

{
  statistics: {
    total_messages: 345,
    last_message_id: 372,
    last_message_posted_at: 2012-03-30T05:43:25Z
  }
}

XML request for the general database status

Request

http://www.ufoseti.org/api/v1/messages/status.xml

Responce

<?xml version="1.0" encoding="UTF-8"?>
<statistics>
  <total-messages type="integer">345</total-messages>
  <last-message-id type="integer">372</last-message-id>
  <last-message-posted-at type="datetime">2012-03-30T05:43:25Z</last-message-posted-at>
</statistics>

JSON request return the database status for stecific country

Request

http://www.ufoseti.org/api/v1/messages/status.json?countries=ru,ee,lv,lt

Responce

{
  statistics: {
    total_messages: 115,
    last_message_id: 321,
    last_message_posted_at: 2011-11-25T05:43:25Z
  }
}

JSON request with no messages matching

Request

http://www.ufoseti.org/api/v1/messages/status.json?countries=za

Responce

{
  statistics: {
    total_messages: 0
  }
}

Specific message

UfoSeti API provides along with general statistics an opportunity to retrieve a details for certain message. In order to do so, client allpication is expected to send the following request:

http://www.ufoseti.org/api/v1/messages/1.(:format)?(locale=:locale)

where parameters are:

format - an expected output format. Possible options: JSON, XML. Default is: JSON.
locale - translation locale the message is expected to be returned. The paramater expected to be sent in ISO 3166-1 alpha-2 (two caracter code). This is an optional parameter, Default is : en.

JSON request for message in specific locale

Request

http://www.ufoseti.org/api/v1/messages/7.json

Responce

{
  message: {
    id: 7,
    observed_at: 2010-01-14T015:23:25Z,
    place: 'Marjamagi Village',
    note: 'Additional Info',
    comment: 'Moderator\'s comment',
    direction: 'North',
    shape: 'Triangle',
    investigation_status: 'Unconfirmed',
    country: 'RU',
    media: []
  }
}

JSON request for message in default locale

Request

http://www.ufoseti.org/api/v1/messages/7.json?locale=ru

Responce

{
  message: {
    id: 7,
    observed_at: 2010-01-14T015:23:25Z,
    place: 'Поселок Марямяги',
    note: 'Второе сообщение 5',
    comment: nil,
    direction: 'Север',
    shape: 'Треугольный',
    investigation_status: 'Непроверено',
    country: 'RU',
    media: []
  }
}

XML request for message in specific locale

Request

http://www.ufoseti.org/api/v1/messages/7.xml?locale=en

Responce

<?xml version="1.0" encoding="UTF-8"?>
<message>
  <id type="integer">7</id>
  <observed-at type="datetime">2010-01-14T015:23:25Z</observed-at>
  <place>Marjamagi Village</place>
  <note>Additional Info</note>
  <comment>Moderator's comment</comment>
  <direction>North</direction>
  <shape>Triangle</shape>
  <investigation_status>Unconfirmed</investigation_status>
  <country>RU</country>
  <media type="array"/>
</message>

JSON reuest for non-existed massage

Request

http://www.ufoseti.org/api/v1/messages/15.json?locale=en

Responce

{
  error: {
    description: 'Message not exist'
  }
}

Multiple mesages

На ряду с получением деталей конкретного сообщения, имееться так же возможность получения нескольких сообщений за один запрос (сообщения выдаются в обратном хронологическом порядке):

 http://www.ufoseti.org/api/v1/messages.(:format)?(locale=:lacale)&(countries=:country)&(limit=:limit)

where parameters are:

format - an expected output format. Possible options: JSON, XML. Default is: JSON.
locale - указание на язык в котором сообщения будут возвращены. Возможные варианты: указыватся по стандарту ISO 3166-1 alpha-2 (двух символьным кодом). Данный параметр являеться необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: en.
countries - фильтрация сообщений по странам. Обозначения стран указыватся по стандарту ISO 3166-1 alpha-2(двух символьным кодом), коды должыны быть перечисленны через запятую, без пробелов. Данный параметр являеться необязательным и может быть опущен, в таком случае будут выданы все последние присланные сообщения.
limit - лимитирование количества возвращаемых сообщений. Данный параметр являеться необязательным и может быть опущен, в таком случае будет использовано значение по умолчанию: 20.

JSON запрос возвращающих детали послених сообщений в стандартной локали

Request

http://www.ufoseti.org/api/v1/messages.json

Responce

{
  messages: [
    {
      id: 2,
      observed_at: "2010-01-14T015:23:25Z",
      place: "Mars Village",
      note: "Additional Info 1",
      comment: "Moderator's comment",
      direction: "North",
      shape: "Triangle",
      investigation_status: "Unconfirmed",
      country: 'EE',
      media: []
    },
    {
      id: 1,
      observed_at: "2010-01-11T023:17:41Z",
      place: "Mars Village",
      note: "Additional Info 2",
      comment: "Moderator's comment",
      direction: "North",
      shape: "Triangle",
      investigation_status: "Unconfirmed",
      country: 'LV',
      media: []
    }
  ]
}

XML запрос возвращающих детали послених сообщений в стандартной локали

Request

http://www.ufoseti.org/api/v1/messages.xml

Responce

<?xml version="1.0" encoding="UTF-8"?>
<messages type="array">
  <message>
    <id type="integer">7</id>
    <observed-at type="datetime">2010-01-14T015:23:25Z</observed-at>
    <place>Mars Village</place>
    <note>Additional Info</note>
    <comment>Moderator's comment</comment>
    <direction>North</direction>
    <shape>Triangle</shape>
    <investigation_status>Unconfirmed</investigation_status>
    <country>LV</country>
    <media type="array"/>
  </message>
  ...
  <message>
    <id type="integer">1</id>
    <observed-at type="datetime">2010-01-11T023:17:41Z</observed-at>
    <place>Mars Village</place>
    <note>Additional Info</note>
    <comment>Moderator's comment</comment>
    <direction>North</direction>
    <shape>Triangle</shape>
    <investigation_status>Unconfirmed</investigation_status>
    <country>LV</country>
    <media type="array"/>
  </message>
</messages>

JSON запрос возвращающих детали послених сообщений в указаной локали

Request

http://www.ufoseti.org/api/v1/messages.json?locale=ru

Responce

{
  messages: [
    {
      id: 7,
      observed_at: "2010-01-14T015:23:25Z",
      place: "Poselok Mars",
      note: "Second message 2",
      comment: nil,
      direction: "Север",
      shape: "Треугольный",
      investigation_status: "Непроверено",
      country: 'LV',
      media: []
    },
    ...
    {
      id: 1,
      observed_at: "2010-01-11T023:17:41Z",
      place: "Poselok Mars",
      note: "Second message 1",
      comment: nil,
      direction: "Север",
      shape: "Треугольный",
      investigation_status: "Непроверено",
      country: 'LV',
      media: []
    }
  ]
}

JSON запрос возвращающих детали послених сообщений ограницивающий их колличество

Request

http://www.ufoseti.org/api/v1/messages.json?locale=ru&limit=3

Responce

{
  messages: [
    {
      id: 7,
      observed_at: "2010-01-14T015:23:25Z",
      place: "Поселок Марямяги",
      note: "Второе сообщение 5",
      comment: nil,
      direction: "Север",
      shape: "Треугольный",
      investigation_status: "Непроверено",
      country: 'RU',
      media: []
    },
    {
      id: 6,
      observed_at: "2010-01-14T015:23:25Z",
      place: "Поселок Марямяги",
      note: "Второе сообщение 4",
      comment: nil,
      direction: "Север",
      shape: "Треугольный",
      investigation_status: "Непроверено",
      country: 'RU',
      media: []
    },
    {
      id: 5,
      observed_at: "2010-01-14T015:23:25Z",
      place: "Поселок Марямяги",
      note: "Второе сообщение 3",
      comment: nil,
      direction: "Север",
      shape: "Треугольный",
      investigation_status: "Непроверено",
      country: 'RU',
      media: []
    }
  ]
}