TED data API — SPEND NETWORK API DOCUMENTATION
First published on 14th March 2014
1. AIMS AND OBJECTIVE
This document outlines the resources available in the Spend Network API.
2. INTRODUCTION TO THE API
The Spend Network database contains records of transactions (that is spending) between UK public sector organisations and their suppliers. The primary fields in each transaction record describe: a) transaction date, b) buyer, c) supplier, and d) amount spent.
In its current version, the Spend Network API enables developers to list and to view transactions for a single buyer. There is also a “discovery” resource which returns a list of the UK buyers for which Spend Network currently holds transactions.
3. VIEWING THE API
The API data can be browsed in HTML format or in JSON format. When viewed in HTML format it becomes simple to browse and to explore the structure of the data. The data contains hyperlinks that can be used to page through large sets of records. To see an example, load the following page in a web browser:
http://www.spendnetwork.com/api/spend/entity/DCM048_DFCMAS_gov
To see any API resource in JSON format, simply append “?format=json” to the URL. As an example, the above URL is converted to JSON in the following line.
http://www.spendnetwork.com/api/spend/entity/DCM048_DFCMAS_gov/?format=json
KEY URLS
This sections provides details on the structure of the three URL resources exposed by the Spend Network API, specifically:
- RESOURCE 1: Retrieve a list of buyers
- RESOURCE 2: Retrieve the transactions of a selected buyer
- RESOURCE 3: Retrieve a single transaction record in full detail
RESOURCE 1 : RETRIEVE A LIST OF BUYERS
URL:http://www.spendnetwork.com/api/entities/
This provides a list of records, each of which has 3 fields which are described below:
RESOURCE 2: RETRIEVE TRANSACTIONS FOR A SELECTED BUYER
The resource URL is given below. It is necessary to append the ENTITY_ID. ENTITY_ID can be discovered by using RESOURCE 1 (as in the previous section).
URL http://www.spendnetwork.com/api/spend/entity/
This resource provides a list of records, each of which has five fields which are described below.
- TRANS_ID — Spend Network’s unique ID for this transaction. E.g. DCM048_DFCMAS_gov_2011_04_36
- AMOUNT_EXECUTED — Numeric amount of this transaction that is how much was spent.
- SUPPLIER_SOURCE_STRING — Name of the supplier. This is the name that is given in the raw data that is uploaded.
- DATE_COMPLETED — Date at which the transaction was completed.
- FULL_DETAILS — This is a hyperlink to the ‘detail’ record for this transaction. An example is:
http://www.spendnetwork.com/api/spend/detail/DCM048_DFCMAS_gov_2011_04_36/
RESOURCE 3: RETRIEVE A SINGLE TRANSACTION RECORD IN DETAIL
The URL to access this resource is given below. It is necessary to append the TRANS_ID key for the record required. Obtaining a TRANS_ID is described in detail in the section describing RESOURCE 2.
URL: http://www.spendnetwork.com/api/spend/detail/
This resource returns a record comprising key value pairs. The record comprises all of the data made available by in the raw data that is uploaded in the Spend Network database.
An example record can be seen by opening the following page: http://www.spendnetwork.com/api/spend/detail/DEC066_DOEACC_gov_2011_04_102
TENDER ELECTRONIC DAILY (TED) API DOCUMENTATION
1. INTRODUCTION
This documentation explains how to use the Spendnetwork draft ‘TED’ API. This API enables developers to access the detailed, historic tender information from across the EU that is published in the Official Journal of the European Union (OJEU). SpendNetwork’s API sources this Open Data from the XML feeds provided by the digital version of OJEU which known as Tender Electronic Daily (TED) http://ted.europa.eu. OJEU / TED notices cover almost all tenders let by public bodies in the EU with an estimated contract value in excess of a threshold (currently about £130,000).
This note provides a brief overview of the tender data available and a practical guide to accessing data via the draft API.
2. OVERVIEW OF THE ‘TED’ API DATASET
The Spend Network TED API provides access to historic TED structured documents published from mid-2007 up to the current day. SpendNetwork downloads recent notices in XML format from the TED website and uploads them into a normalized and searchable database.
The basic unit of information in TED is a published Notice which has the purpose of notifying an upcoming tendering opportunity, the award of a contract, or of some other information related to a tender. Wihtin the dataset , Notices often have a common tender identifier (tender_id).
Within notices (and hence tenders), data is provided in both structured and semi-structured form. Structured data includes Common Procurement Vocabulary (CPV) codes for each tender, notice date and broad industry sector. Semi-structured data found under different headings in the notices’ document text sections include estimated tender value, details relating to the buyer organisation, whether the tender is a framework and other fields that are of potential interest in purchasing or market research.
Note:
The API is currently in draft form and comments would be welcomed from prospective developers. Please note that the data in the API is provided much as we receive it in the XML feed with limited further aggregation, data-cleaning, sample checking or linking. Nonetheless the data contains valuable insights into buyer behaviour in the public sector and suggestions on post-processing from prospective users are welcomed.
3. USING THE API
The API data can be browsed in HTML format or in JSON format. When viewed in HTML format it becomes simple to browse and to explore the structure of the data within a web browser. The data contains hyperlinks that can be used to page through large sets of records.
The base URL (returning an HTML page) is as follows:
http://spendnetwork.com/api/ted_search/
Notes:
- A list of tenders is returned along with a summary ‘count’ of the total number of records found. Details of the fields are provided in “Tender Fields” section below.
- To filter the list of tender returned, it is necessary to append ‘GET’ query parameters to the URL. The set of possible search parameters are given in the documentation at the top of the HTML page that is returned. This documentation is reproduced below in the “Search Parameters” section.
- To acquire a page in JSON format, simply append “?format=json” to the above URL.
4. TENDER FIELDS
Each page returned by the API brings back 20 tender records. The fields for each record are described below.
- TENDER_ID — The unique identifier for this tender provided by TED.
- ISOCOUNTRY — Two letter country code for the buyer organisation’s country (e.g. UK, FR)
- CPV_CODES — Common Purchasing Vocabulary information.
- TENDER DOCUMENTS — A list of published notices attached to this tender. Please refer to TENDER DOCUMENT FIELDS below.
- Organisations — A list of organisations related to this tender. An Organisation in this list can be either a buyer or a supplier.
CPV_CODES comprises a list of codes and code descriptions. For example: [{“code”: “45432100”, “description”: “Floor laying and covering work” }]
It should be noted that CPV codes are structured hierarchically in syntax. The overall ancestor of code 45432100 is code 45000000 (‘Construction Work’).
Note: the following documentation resource is useful in gaining an understanding of CPV codes: http://simap.europa.eu/codes-and-nomenclatures/codes-cpv/codes-cpv_en.htm
5. TENDER DOCUMENT FIELDS
Each tender record contains a list of documents associated with that tender. The fields in each tender document are described below.
- ID — The unique identifier of this notice.
- title — The title given to the tender in the document text under a title heading
- subtitle — The title given to the tender in the document text under a subtitle heading
- natnotice — The nature of the notice, e.g. ‘contract notice’, ‘contract award’
- datepub — Publication date with format YYYY-MM-DD
- documentvalue ⋅⋅ description (text) ⋅⋅ currency (text) ⋅⋅ value text (text) ⋅⋅ The amount field is derived from the ‘value text’ given in the document.
- document milestone ⋅⋅ description (text) ⋅⋅ milestone (date with format DD/MM/YYYY)
- document text — The document text normally includes a title and subtitle but may include other fields. This field provides a link to this data.
6. SEARCH PARAMETERS
As noted above the entry point to SpendNetwork’s ‘TED’ API is:
http://spendnetwork.com/api/ted_search/
This returns the first page of all results held in the database. To filter the result list, ‘GET‘ query parameters can be added by altering the URL as follows:
http://spendnetwork.com/api/ted_search?PARAMETER1=REQUIRED_VALUE1&PARAMETER2=REQUIRED_VALUE2
A working example that searches for UK (country_code=UK) tender documents published after 1 Mar 2013 (date_from=01–03–2013) is as follows:
http://spendnetwork.com/api/ted_search/?date_from=01-03-2013&page=2&country_code=UK
The full set of search parameters currently available is provided below:
- country_code — Two letter string. E.g. ‘UK’ or ‘FR’ — Returns all tenders records whose buyer is located in the specified country.
- date_from — Date with format DD-MM-YYYY — Returns all tenders containing a document published after or on this date
- date_to — Date with format : DD-MM-YYYY — Returns all tenders containing a document published after or on this date
- cpv_code — Text string (with a length of 8 characters) — Returns tenders marked with this code. Note a list of codes can be found at the URL resource below: http://simap.europa.eu/codes-and-nomenclatures/codes-cpv/codes-cpv_en.htm
- include_child_cpvs — Text string with a length of 1 character and values of ‘1’ or ‘0’. If the parameters is set to ‘1’ then the search will be expanded to include any child codes. For example codes 34120000 (Motor vehicles for the transport of 10 or more persons) and ‘34114000’ (specialist vehicles) are child codes of code ‘34110000’ (‘passenger cars’) which is a child of code ‘34100000’ (motor vehicles etc)
- organisation — Text string with a single word — Will bring back any tenders that have this organisation as either a buyer or a supplier.
[UIColor colorWithRed:0.07 green:0.2 blue:0.27 alpha:1]
Originally published at spendnetwork.github.io.
