OpenData - API: Περιγραφή και Οδηγός χρήσης
Το opendata.bankofgreece.gr αποτελεί την Πύλη Ανοικτών Δεδομένων της Τράπεζας της Ελλάδος. Μέσω της πύλης διατίθενται στους ερευνητές και στο ευρύ κοινό στατιστικά σύνολα δεδομένων σε μηχαναγνώσιμη μορφή. Η συλλογή, επεξεργασία και δημοσίευση των δεδομένων πραγματοποιείται βάσει διεθνών προτύπων για ανοικτά δεδομένα.
Περιγραφή API
Το API έχει σχεδιαστεί σύμφωνα με τις αρχές του REST.
Μέσω αυτού, έχετε τη δυνατότητα πρόσβασης σε όλα τα δεδομένα της Τράπεζας της Ελλάδος με ταχύτητα και ευκολία, αποκτώντας πληροφορίες για διάφορους σκοπούς.
Το API διαθέτει προβλέψιμα URLs, ειδικά διαμορφωμένα για κάθε σύνολο δεδομένων. Δέχεται αποκλειστικά GET κλήσεις, χωρίς δεδομένα στο σώμα του request, και επιτρέπει τη χρήση συγκεκριμένων παραμέτρων στα URLs για περαιτέρω παραμετροποίηση των αποτελεσμάτων.
Οι απαντήσεις επιστρέφονται σε μορφή JSON και χρησιμοποιούν τυπικούς κωδικούς απόκρισης HTTP, χωρίς να απαιτείται έλεγχο ταυτότητας χρήστη (authentication).
Στη σελίδα κάθε συνόλου δεδομένων, υπάρχει επιλογή "Λήψη δεδομένων απο API", μέσω της οποίας μπορείτε να δείτε ένα δείγμα κώδικα (snippet), το URL και ο τρόπος πρόσβασης στα δεδομένα του συγκεκριμένου συνόλου.
const requestOptions = {method: "GET"};fetch("https://ods.opendata.bankofgreece.gr/api/OfficeRentIndex", requestOptions).then((response) => response.text()).then((result) => console.log(result)).catch((error) => console.error(error));
Έλεγχος ταυτότητας χρήστη (authentication)
Τα δεδομένα που παρέχονται από το API είναι ανοικτά και προσβάσιμα σε όλους, χωρίς να απαιτείται κλειδί ταυτοποίησης. Οι κλήσεις πραγματοποιούνται με χρήση GET μεθόδου και επιστρέφουν τα αποτελέσματα σε μορφή JSON.
curl --request GET https://ods.opendata.bankofgreece.gr/api/OfficePriceIndex
Σφάλματα
Το API χρησιμοποιεί συμβατικούς HTTP κωδικούς απόκρισης, για να υποδείξει την επιτυχία ή αποτυχία της κλήσης.
-Κωδικοί της μορφής 2ΧΧ, υποδηλώνουν επιτυχία.
-Κωδικοί στην μορφή 4ΧΧ, υποδηλώνουν σφάλματα, στα δεδομένα που δόθηκαν κατά την κλήση. Για παράδειγμα, λάθος παράμετροι στα φίλτρα της κλήσης.
-Κωδικοί 5ΧΧ, ενημερώνουν για σφάλματα στον server.
Κάθε απάντηση, επιστρέφει παράμετρο (message), με την επεξήγηση του σφάλματος αναλυτικότερα.
200 OK Επιτυχημένη κλήση.400 Bad Request Η κλήση είναι λανθασμένη, και οιπαράμετροι που δόθηκαν δεν είναι σωστοί.402 Request Failed Οι παράμετροι είναι σωστοί αλλά η κλήση απέτυχε.404 Not Found Η ζητούμενη οντότητα δεν υπάρχει.500, 502, 503, 504 Σφάλματα στον server.
Παράμετροι κλήσης
Όλες οι κλήσεις του API, μοιράζονται κοινή δομή και δέχονται οποιονδήποτε συνδυασμό των παρακάτω παραμέτρων: $select, $filter, $orderby, $first, $after.
$select: Λίστα των πεδίων που θέλουμε να επιστραφούν, με κόμμα χωρισμένα.
$filter: Μια έκφραση OData (μια έκφραση που επιστρέφει μια λογική τιμή) που χρησιμοποιεί τα πεδία της οντότητας για την ανάκτηση ενός υποσυνόλου των αποτελεσμάτων.
$orderby: Ταξινομεί τα αποτελέσματα με βάση λίστα πεδίων χωρισμένη με κόμμα. Προσθήκη Desc για φθίνουσα ταξινόμηση, διαφορετικά Asc για αύξουσα.
$first: Ακέραια τιμή που καθορίζει τον αριθμό των στοιχείων που θα επιστραφούν. Η προεπιλογή είναι 100. Για λήψη όλων των δεδομένων μπορεί να χρησιμοποιηθεί η τιμή -1 (υπάρχουν περιορισμοί).
$after: Αλφαριθμητική σειρά, που επιστρέφεται σε κάθε κλήση. Βοηθάει στη σελιδοποίηση των δεδομένων με βάση τον αριθμό των στοιχείων λήψης κάθε σελίδας ($first).
Requesthttps://ods.opendata.bankofgreece.gr/api/AggregatedBalanceSheetItemsOfUCITSInvestmentFunds?$select=AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID,AssetsTotalBond,ReferenceDate&$filter=AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID%20gt%20107&$first=10&$after=W3siRW50aXR5TmFtZSI6IkFnZ3JlZ2F0ZWRCYWxhbmNlU2hlZXRJdGVtc09mVUNJVFNJbnZlc3RtZW50RnVuZHMiLCJGaWVsZE5hbWUiOiJBZ2dyZWdhdGVkQmFsYW5jZVNoZWV0SXRlbXNPZlVDSVRTSW52ZXN0bWVudEZ1bmRzSUQiLCJGaWVsZFZhbHVlIjoxMDAsIkRpcmVjdGlvbiI6MH1dResponse{"value": [{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 108,"AssetsTotalBond": 1089.06,"ReferenceDate": "2012-12-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 109,"AssetsTotalBond": 1144.52,"ReferenceDate": "2013-01-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 110,"AssetsTotalBond": 1118.77,"ReferenceDate": "2013-02-28"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 111,"AssetsTotalBond": 1082.49,"ReferenceDate": "2013-03-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 112,"AssetsTotalBond": 1131.95,"ReferenceDate": "2013-04-30"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 113,"AssetsTotalBond": 1176.71,"ReferenceDate": "2013-05-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 114,"AssetsTotalBond": 1114.13,"ReferenceDate": "2013-06-30"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 115,"AssetsTotalBond": 1129.99,"ReferenceDate": "2013-07-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 116,"AssetsTotalBond": 1012.95,"ReferenceDate": "2013-08-31"},{"AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID": 117,"AssetsTotalBond": 955.8,"ReferenceDate": "2013-09-30"}],"nextLink": "https://ods.opendata.bankofgreece.gr/api/AggregatedBalanceSheetItemsOfUCITSInvestmentFunds?$select=AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID,AssetsTotalBond,ReferenceDate&$filter=AggregatedBalanceSheetItemsOfUCITSInvestmentFundsID%20gt%20107&$first=10&$after=W3siRW50aXR5TmFtZSI6IkFnZ3JlZ2F0ZWRCYWxhbmNlU2hlZXRJdGVtc09mVUNJVFNJbnZlc3RtZW50RnVuZHMiLCJGaWVsZE5hbWUiOiJBZ2dyZWdhdGVkQmFsYW5jZVNoZWV0SXRlbXNPZlVDSVRTSW52ZXN0bWVudEZ1bmRzSUQiLCJGaWVsZFZhbHVlIjoxMTcsIkRpcmVjdGlvbiI6MH1d"}
Κατηγορίες
Αυτή η μέθοδος, επιστρέφει πληροφορίες για μία ή περισσότερες κατηγορίες ή υποκατηγορίες, που χρησιμοποιούνται για την ομαδοποίηση των διαθέσιμων συνόλων δεδομένων (DataSets).
curl --request GET https://ods.opendata.bankofgreece.gr/api/Categoriescurl --request GET https://ods.opendata.bankofgreece.gr/api/Categories/CategoryID/{CategoryID}
Σύνολα Δεδομένων
Αυτή η μέθοδος, επιστρέφει πληροφορίες για ένα ή περισσότερα σύνολα δεδομένων και τα μεταδεδομένα τους.
curl --request GET https://ods.opendata.bankofgreece.gr/api/DataSetscurl --request GET https://ods.opendata.bankofgreece.gr/api/DataSets/DataSetID/{DataSetID}
Συσχετισμός Κατηγορίες-Σύνολα Δεδομένων
Αυτή η μέθοδος, επιστρέφει πληροφορίες για ένα ή περισσότερα σύνολα δεδομένων και τις αντίστοιχες κατηγορίες που ανήκουν.
curl --request GET https://ods.opendata.bankofgreece.gr/api/DataSetCategoriescurl --request GET https://ods.opendata.bankofgreece.gr/api/DataSetCategories/DataSetId/{DataSetId}/CategoryId/{CategoryId}
Συσχετισμός Συνόλου Δεδομένων-Δείκτες
Αυτή η μέθοδος, επιστρέφει τους δείκτες που απαρτίζουν κάθε σύνολο δεδομένων με τα αντίστοιχα μεταδεδομένα τους.
curl --request GET https://ods.opendata.bankofgreece.gr/api/DataSetColumnscurl --request GET https://ods.opendata.bankofgreece.gr/api/DataSetColumns/DataSetColumnID/{DataSetColumnID}
Συσχετισμός Συνόλου Δεδομένων - Δείκτες λεκτικών
Κάποια σύνολα, περιέχουν δείκτες που δεν έχουν αριθμητικές τιμές. Αυτός ο συσχετισμός με τους λεκτικούς δείκτες επιστρέφεται σε αυτή την μέθοδο.
curl --request GET https://ods.opendata.bankofgreece.gr/api/DataMappingscurl --request GET https://ods.opendata.bankofgreece.gr/api/DataMappings/DataMappingID/{DataMappingID}
Παράδειγμα λήψης δεδομένων
Παρακάτω παρουσιάζεται ένα παράδειγμα λήψης δεδομένων
- Λαμβάνουμε πληροφόρηση για τα διαθέσιμα σύνολα δεδομένων (DataSets)
https://ods.opendata.bankofgreece.gr/api/DataSets - Εστιάζουμε στο DataSet "Δείκτης Μισθωμάτων Καταστημάτων" με DataSetID=179 και κρατάμε το διακριτικό του DataSet DataSetName
https://ods.opendata.bankofgreece.gr/api/DataSets/DataSetID/179 - Από τον Frequency καταλαβαίνουμε πως τα δεδομένα μας είναι Εξαμηνιαία
- Κάνουμε λήψη όλων των δεικτών που μας ενδιαφέρουν για το συγκεκριμένο Σύνολο Δεδομένων - DataSet
https://ods.opendata.bankofgreece.gr/api/DataSetColumns?$filter=DataSetID eq 179 - Κρατάμε να χρησιμοποιήσουμε το ReferenceDate ως κύρια Ημερομηνία Αναφοράς και τον δείκτη RetailRentIndexAthens δηλ. "Δείκτης μισθωμάτων καταστημάτων Αθήνα"
- Τέλος, κάνουμε λήψη όλων των δεδομένων για το συγκεκριμένο DataSet με βάση το DataSetName που είχαμε προηγουμένος, και ζητάμε τον δείκτη που μας ενδιάφερει καθώς και την περίοδο αναφοράς
https://ods.opendata.bankofgreece.gr/api/RetailRentIndex?$first=-1&$select=ReferenceDate,RetailRentIndexAthens - Αν ενδιαφερόμαστε για τα τρέχοντα δεδομένα (χωρίς τις αναθεωρήσεις) τότε αλλάζουμε την παραπάνω κλήση σε:
https://ods.opendata.bankofgreece.gr/api/RetailRentIndex?$first=-1&$select=ReferenceDate,RetailRentIndexAthens&$filter=ValidUntil eq null