Spend Network's summary endpoint provides a simplified JSON output that provides a flatter, smaller, more consistent output. This enables lower volumes of data to travel into databases and more consistent and easier parsing of the data.

JSON Output Structure and Information Design Principles

The JSON output for the API has been meticulously structured to ensure clarity, consistency, and ease of use. The following key principles have been adopted in its design:

1. A single document structure for all records

• Consistency: All records, whether tender notice, planning or contract awards contain the same fields and all fields deploy consistent data structures at all times. This ensures that simple validation routines can be written for each document (e.g. a checksum for the total number of fields).
• Use: Tender documents will contain fields for awards data, which will not be populated, it is critical for developers to use release_tags to determine the nature of the published document before accessing the appropriate data.

 

2. Clear and Descriptive Naming Conventions

• Consistency: Each key follows a consistent naming pattern that aids in easy identification and understanding. For example, all monetary values related to awards are prefixed with award_, making it straightforward to locate and differentiate from other values like tender_.
• Descriptiveness: Keys are named descriptively to convey the precise information they hold. For instance, buyer_address_country_name clearly indicates it stores the country name of the buyer's address.

 

3. Logical Grouping of Related Information

• Categorisation: Related data points are grouped together logically. For example, all keys related to buyer information start with buyer_ (e.g., buyer_name, buyer_address_country_name), ensuring that similar information can be found in proximity.
• Hierarchical Structure: Our data is broadly flat, but the small amount of hierarchy helps users navigate the data efficiently, recognizing patterns and relationships between different pieces of information.

 

4. Effective handling of one to many relationships

• Managing edge cases: In rare cases contract award notices are published as an extension to a tender notice, in still rarer circumstances there are more than one award published against a given tender. We handle this dynamically, collating data where appropriate (e.g in the award_titles) and using the first award found in fields where referential integrity is essential. This is the case in fields with the _first suffix.
• Implications: In some cases it is possible that only the first award from a set of multiple awards is being documented. In this context developers can use our complete API to gather additional records from the original published releases where necessary.

 

5. Comprehensive Data Coverage

• Detailed Information: The JSON structure includes extensive details covering various aspects such as buyer details, award values in multiple currencies, tender specifics, and more. This comprehensive coverage ensures users have all necessary data in one place.
• Multiple Data Types: The structure accommodates various data types including strings, numbers, arrays, and booleans, to accurately represent different kinds of information.

 

6. Timestamp and Date Management

• ISO 8601 Format: All date and time values are provided in ISO 8601 format (e.g., 2021-12-17T08:27:49Z), a widely accepted standard that supports interoperability and ease of parsing across different systems.
• Clear Distinction Between Dates: Different types of dates such as release_date, start_date, and closing_date are clearly differentiated, ensuring precise tracking of timelines.

 

7. Nullability for Optional Fields

• Explicit Nulls: Fields that might not always have a value (e.g., contact_url, buyer_address_street_address) are included with a null value when applicable, maintaining a consistent structure while signalling optional data.

 

8. Array Utilization for Multiple En

• Lists for Multiple Items: Fields that can have multiple entries, such as supplier_names, cpv_names, and supplier_ids, are represented as arrays. This approach ensures flexibility and scalability in handling multiple values.

 

9. Identification and Referencing

• Unique Identifiers: Keys like ocid and tender_id are used to provide unique identifiers for contracts and tenders, supporting traceability and integration with other datasets. Where we are able to we will supply identifiers for suppliers with a unique id for companies to reconcile to the source.
• References: Fields such as references_ocids allow for linking related documents or entities, facilitating comprehensive data analysis.

 

10. Currency and Value Clarity

• Explicit Currency Indicators: Monetary values are accompanied by currency indicators (e.g., award_currency_first, tender_currency), ensuring that users can accurately interpret financial data.
• Multiple Currency Representations: Values are provided in different currencies (USD, GBP, EUR) to cater to a diverse range of users and use cases.

 

11. Status and Metadata Information

• Status Indicators: Fields like tag_status and dps_pred offer status information, helping users understand the current state and categorization of the data.
• Metadata for Traceability: Metadata fields such as date_created and date_updated provide insights into the data's lifecycle, aiding in version control and auditing.

This structured approach ensures that the JSON output is both user-friendly and comprehensive, facilitating efficient data retrieval and analysis for diverse applications.

 

Example document

This example document shows how our summary api data is structured and published.

{
  "_index": "sn-api-ocds-gold-v3-prod",
  "_id": "ocds-0c46vo-0001-12ef087c-3ad3-4d72-b2bb-e3d416081402",
  "_score": 1,
  "_source": {
    "has_attachment": "true",
    "cpv_names": [
      "Education and training services",
      "Personnel services except placement and supply services",
      "Specialist training services"
    ],
    "tender_url": "https://www.contractsfinder.service.gov.uk/Notice/12ef087c-3ad3-4d72-b2bb-e3d416081402",
    "closing_date": null,
    "awards_usd_value": 0,
    "date_updated": "2024-01-18T02:40:12.144016",
    "buyer_address_country_name": "United Kingdom",
    "buyer_name": "DRIVER AND VEHICLE STANDARDS AGENCY",
    "tender_id": "tender_362771/1301350",
    "language": "en",
    "source": "cf_notices",
    "release_tags": "planning",
    "ocid": "ocds-0c46vo-0001-12ef087c-3ad3-4d72-b2bb-e3d416081402",
    "tag_status": "open",
    "tender_title": "Tailored Executive Development"
  }
}

The following shows an example of a document where lotting features have been identified and collected.

{
  "ocid": "ocds-0c46vo-0001-036588-2025_036588-2025",
  "start_date": "2025-09-04T00:00:00+01:00",
  "tender_gbp_value": 10000000,
  "lots": {
    "lot_descriptions": [
      "1: Strategic investment business, organisational strategy...",
      "2: Target Operating Model design and delivery...",
      "3: Specialist investment consultancy services..."
    ],
    "lot_ids": ["1", "2", "3"],
    "lot_total_value": 10000000.0,
    "lot_count": 3,
    "lot_amounts": [3500000.0, 3500000.0, 3000000.0]
  }
}

 

Field list

Below we have grouped fields and listed each possible field then and provided a field type and description.

 

Currencies and conversion

Our currency output adheres to international currency standards by using ISO 4217 codes for currency representation. This ensures that monetary values are clearly identified and standardised across different datasets, facilitating accurate interpretation and conversion.

We use exchangeratesapi.io for currency conversion, which provides accurate and up-to-date exchange rates sourced from reliable financial data providers.

Code	Field type	Description
award_currency_first	String	The original currency of an award notice as published in the source data.
award_amount_sum	Value	The original value of an award as published in the source data.
awards_usd_value	Value	The value of award_amount_sum converted to USD.
awards_gbp_value	Value	The value of award_amount_sum converted to GBP.
awards_eur_value	Value	The value of award_amount_sum converted to EUR.
tender_currency	String	The original currency of a tender notice as published in the source data.
tender_amount	Value	The original value of a tender as published in the source data.
tender_usd_value	Value	The value of tender_amount converted to USD.
tender_gbp_value	Value	The value of tender_amount converted to GBP.
tender_eur_value	Value	The value of tender_amount converted to EUR.

 

Entities and Organisations

During our input process we are cleansing fields to provide reliable consistent values across both buyer names and addresses. In some cases we also match supplier identifiers.

Name	Field type	Description
buyer_name	String	The name of the buying entity or organisation.
buyer_address_country_name	String	The name of the country where the buyer's address is located.
buyer_address_locality	String	The locality or city where the buyer's address is situated.
buyer_address_region	String	The region where the buyer's address is situated.
supplier_names	String	The names of the suppliers involved in the contract or tender.
supplier_ids	List of strings	Unique identifiers for the suppliers, such as registration or company numbers.
buyer_address_street_address	String	The street address of the buyer.
buyer_address_iso_alpha2	String	ISO 3166-1 alpha-2 code for the buyer's country.

 

Dates and Times

Field Name	Field type	Description
award_start_date_first	Date time	The contract start date for the first published award.
award_end_date_first	Date time	The contract end date for the first published award.
release_date	Date time	The publisher's own record for the date the document was published.
date_updated	Date time	The most recent modification date.
tender_end_date	Date time	The deadline for submissions on tenders.
date_created	Date time	The date gathered by Spend Network.

 

Document identifiers

Field Name	Field type	Description
tender_id	String	The identifier provided by the publisher.
ocid	String	Spend Network's unique identifier, compliant with the Open Contracting Data Standard.
references_ocids	String	Additional records linked as potential duplicates.

 

Status and Metadata

Field Name	Data Type	Description
source	String	The name of the source code used to harvest the data.
release_tags	String	The document type: 'tender', 'award', or 'planning'.
tag_status	String	Whether a contract is "open" or "closed".
dps_pred	Boolean	Whether this is a framework or dynamic purchasing system contract.
language	String	ISO 639 language classification.

 

Descriptions and Titles

Field Name	Data Type	Description
tender_title	String	The title of the tender.
content	String	Combined tender title and description for text searching.
tender_description	String	Detailed description of the tender.
award_descriptions	String	Descriptions of awards associated with the tender.
award_titles	String	Titles of awards associated with the tender.

 

Contact Information

Field Name	Data Type	Description
contact	String	The email address of the contact person or entity.
contact_url	String	URL for contact information.

 

Classification Codes

Field Name	Data Type	Description
cpv_names	Array	CPV names provided by the original publisher.
cpv_aug_names	Array	Augmented CPV names added by Spend Network.
cpv_aug_codes	Array	Augmented CPV codes added by Spend Network.
cpv_codes	Array	CPV codes provided by the original publisher.

 

URLs

Field Name	Data Type	Description
tender_url	String	The original source URL of the published tender.

 

Lots

Field name	Data Type	Description
lots.lot_count	Integer	The number of lots in the tender or award.
lots.lot_ids	Array of Strings	Identifiers for each individual lot.
lots.lot_titles	Array of Strings	Titles of each lot.
lots.lot_descriptions	Array of Strings	Descriptive narrative for each lot.
lots.lot_amounts	Array of Numbers	Monetary values for each lot.
lots.lot_total_value	Number	Total value of all lots combined.
lots.lot_primary_currency	String	ISO 4217 currency code for lot amounts.

 

Attachments

Field Name	Data Type	Description
has_attachments	Boolean	Whether the document has attachments.
attachments	Array	List of attachment URLs and titles (when attachment__show is enabled).

 

API requests

 

Accessing the Spend Network API Endpoint

The endpoint URL is: https://api.spendnetwork.cloud/api/v3/notices_summary/read_summary_records

 

Query Parameters

Name	Type	Description
search_term__is	string	Search term to include (maxLength: 100)
search_term__exclude	string	Search term to exclude (maxLength: 100)
buyer_name__is	string	Buyer name to include
supplier_name__is	string	Supplier name to include
buyer_address_country_name__is	string	Country name of the buyer
buyer_address_country_code__is	array[string]	Country codes of the buyer
ocid__is	string	Open Contracting ID to include
release_date__gte	string($date-time)	Release date greater than or equal to
release_date__lte	string($date-time)	Release date less than or equal to
release_tags__is	string	Release tags to include (tender, award, planning)
tag_status__is	string	Tag status to include
cpv__is	array[string]	CPV codes to include
source__is	array[string]	Sources to include
offset	integer	Pagination offset (min: 0, max: 9900)
limit	integer	Number of records to return (min: 0, max: 100)
value__gte	integer	Minimum value
value__lte	integer	Maximum value
attachment__show	boolean	Include attachment URLs and file names
attachment__is	boolean	Show only results with attachments

 

Release Tags

Release tag items can be one or more of the following:

tender
award
planning
award contract
tenderUpdate
awardUpdate
tenderAmendment
planningUpdate
tenderCancellation
contractAmendment
contractTermination

 

Example Python Code

import requests

query = {
    "compiled_only": False,
    "original_only": False,
    "date_direction": "desc",
    "offset": 0,
    "limit": 50,
    "prefix_search": False,
    "release_tags__is": "tender",
    "predicted_cpv_values": False,
    "dedupe__is": False,
}

def object_to_url_search_params(obj):
    params = []
    for key, value in obj.items():
        if isinstance(value, list):
            for item in value:
                params.append((key, item))
        else:
            params.append((key, value))
    return params

url_query = requests.models.PreparedRequest()
url_query.prepare_url("https://api.spendnetwork.cloud/api/v3/notices_summary/read_summary_records", object_to_url_search_params(query))
url = url_query.url

def fetch_summary_api_records():
    try:
        response = requests.get(
            url,
            headers={
                "Accept": "application/json",
                "Content-Type": "application/json",
                "Authorization": "Bearer YOUR_ACCESS_TOKEN",
            },
        )
        response.raise_for_status()
        return response.json()
    except requests.RequestException as error:
        print("Fetch error:", error)
        return None

records = fetch_summary_api_records()
print(records)

 

Authentication

To access the API users need to generate a bearer token by calling the access-token endpoint /api/v3/login/access-token. The payload returns:

{
  "access_token": "string",
  "token_type": "string",
  "expiration_date": "string"
}

 

Pagination

To handle large datasets, use the offset and limit parameters. Note: there is a 10,000 record limit on any single query.

query = {
    "offset": 0,
    "limit": 100
}

while True:
    records = fetch_summary_api_records()
    if not records or len(records) < query["limit"]:
        break
    query["offset"] += query["limit"]

 

Best Practices

• Optimize Queries: Use specific and relevant query parameters to limit the amount of data returned.
• Caching: Implement caching strategies to reduce the number of API calls.
• Error Handling: Ensure robust error handling to manage API errors gracefully.
• Rate Limits: Be mindful of API rate limits and implement retry mechanisms.
• Pagination: Use pagination to handle large datasets efficiently.

 

Document Attachments

Spend Network's summary API supports both sourcing and downloading attachments (e.g. PDFs, DOCs) related to individual tender or contract documents.

 

Filtering For Attachments

Use the attachment__is parameter to return only documents with attachments:

{
  "attachment__is": true,
  "release_tags__is": "award",
  "buyer_name__is": "MINISTRY OF DEFENCE"
}

 

Show Attachment Sources

Use attachment__show to include attachment metadata in responses:

{
  "attachment__show": true,
  "ocid__is": "ocds-0c46vo-0001-12ef087c-3ad3-4d72-b2bb-e3d416081402"
}

Response:

"attachments": [
  {
    "title": "Entwurfsplanung Heizung KG.pdf",
    "url": "https://www.vergabe-westfalen.de/.../Entwurfsplanung+Heizung+KG.pdf"
  }
]

 

Downloading Attachments via Spend Network API

 

1. List Available Attachment Files

Endpoint: POST https://api.spendnetwork.cloud/api/v3/attachments/list

curl -X POST \
  'https://api.spendnetwork.cloud/api/v3/attachments/list' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "source": "td_vergabe_westfalen_de",
        "tender_id": "41878101"
      }'

 

2. Download Specific Attachment File

Endpoint: GET /api/v3/attachments/download/{source}/{tender_id}/{filename}

curl -X GET \
  'https://api.spendnetwork.cloud/api/v3/attachments/download/td_vergabe_westfalen_de/41878101/submissionform_docx' \
  -H 'Accept: application/json'

 

Contact Information

For further assistance or questions about the API, please contact our support team at hello@openopps.com.