Welcome to Mam Zdanie API’s documentation!

Welcome To Mam Zdanie API documentation. Here you will find a complete methods documentation with examples as well.

Calling Methods

In order to call a specific API Method, you need to understand few things:

• API URL: MamZdanie API calls are created by specific URL’s with the following convention:

BASE_URL?AUTH&METHOD&OPTIONS

where:

• BASE_URL it’s a base url for calling API methods and is: https://mamzdanie.org.pl/api/service
• AUTH part is an API key, which you can obtain from your user profile (Twój Profil) and when invoked through API should look like: api_key=b3hf7jnms23hase8902uiosw6hj7445f
• METHOD part defines, which method you want to call, eg: method=get_consultations - for list of methods see below.
• OPTIONS are each method available options, like: active=true

Example API call should look like:

https://mamzdanie.org.pl/api/service?api_key=b3hf7jnms23hase8902uiosw6hj7445f&method=get_consultations&active=true

Obtaining your API key

In order to use Mam Zdanie API you need to be registered as an organization. To be specific:

• if you are registering as a consultation participant (register as Jako uczestnik konsultacji) you should choose to register an institution account (Jestem instytucją)
• or you can register as the organizer of the consultation - then you will always have access to Mam Zdanie API

Then, after you log-in, please click on your profile page (Twój profil), and at the bottom of the page, you will find your API KEY (Twój kod autoryzacyjny API).

API Responses

When invoking Mam Zdanie API methods you will be returned with an XML response which is one of the following:

• correct response - each method has it’s own correct XML response. For example get_consultations method XML response looks like:

  <consultations>
      <consultation>
              <id>18855</id>
              <signature>ACTA-komentarz2012</signature>
              <subject>komentarz MAC do umowy ACTA</subject>
              <dateFrom>21-02-2012 00:00</dateFrom>
              <dateTo>22-03-2012 00:00</dateTo>
              <userName>Malgorzata Steiner</userName>
              <userId>18043</userId>
              <replies>13</replies>
              <url>http://mamzdanie.org.pl/web/guest/konsultacje/-/message_boards/message/18855</url>
              <active>true</active>
              <organizationId>18049</organizationId>
              <organizationName>Ministerstwo Administracji i Cyfryzacji</organizationName>
      </consultation>
  </consultations>

• error response - if an error occurs, an error XML is returned:

  <error>
      <errorDate>20-03-2012 10:57:37</errorDate>
      <errorCode>107</errorCode>
      <errorMsg>Niepoprawny parametr method</errorMsg>
  </error>

Error Responses

Each error response consists of:

• errorDate - when the error occured
• errorCode - error code number
• errorMsg - error message

Here is a complete list of error codes:

• 101 - Invalid key length
• 102 - Invalid key
• 103 - Invalid ID param
• 104 - Given consultation (number) doesn’t exist
• 105 - Username doesn’t exist (user that published the consultation)
• 106 - Organization doesn’t exist (organization that published the consultation)
• 107 - Invalid method parameter
• 500 - Server Error - contact the administrator

API Methods

Here is a complete list of API Methods:

• get_consultations, method options: active=true/false
• get_consultation_details, method options: id=ConsultationID
• get_emiter, method options: id=EmiterID
• get_organization, method options: id=OrganizationID

Examples

This simple example written in Python shows how to get all active consultations:

#
# Copyright (C) 2012 Pretius Sp. z o.o.
#
# Author: Robert Olejnik <rolejnik@pretius.com>
#

# This simple example shows how to display all active consultations

from lxml import etree
import requests

MZ_BASE_URL = "https://mamzdanie.org.pl/api/service"
MZ_API_KEY  = "b7f2a21c345317ec23452359sla2aa08"
MZ_URL      = MZ_BASE_URL + "?api_key=" + MZ_API_KEY + "&method="

method = "get_consultations&active=true"
r = requests.get(MZ_URL + method)
consultations = r.content

root = etree.fromstring(consultations)

if root.tag != "error":
        for consultation in root:
                print "Consultation:"
                for atr in consultation:
                        print " - %s: %s" % (atr.tag, atr.text)
else:
        print "[ERROR] We have occurred an error:"
        print "[ERROR] Code: %s" % root[1].text
        print "[ERROR] Description: %s" % root[2].text

Successful result should be as follows:

teon> python mamzdanie-active_consultations.py
Consultation:
 - id: 18855
 - signature: ACTA-komentarz2012
 - subject: komentarz MAC do umowy ACTA
 - dateFrom: 21-02-2012 00:00
 - dateTo: 22-03-2012 00:00
 - userName: Malgorzata Steiner
 - userId: 18043
 - replies: 13
 - url: http://mamzdanie.org.pl/web/guest/konsultacje/-/message_boards/message/18855
 - active: true
 - organizationId: 18049
 - organizationName: Ministerstwo Administracji i Cyfryzacji

And if an error occurs:

teon> python mamzdanie-active_consultations.py
[ERROR] We have occurred an error:
[ERROR] Code: 102
[ERROR] Description: Niepoprawny klucz