NAV Navbar
The DX Network
API Documentation
Shell
  • Introduction
  • Getting started
  • Authentication
  • Definitions
  • Data Models
  • DX Tech Industry Model
  • DX Tech Industry API
  • DX Semantic API
  • Errors

    • Introduction

    The DX Network is an infrastructure-level structured data marketplace open to anyone.

    It allows marketplace participants to buy and sell structured data from each other in real-time via an API with datapoint granularity. This allows data to be traded in a similar way to how stocks, commodities etc. are traded on market exchanges, effectively creating the first data exchange.

    The initial data marketplace launched on the DX Network focuses on the exchange of data about the Technology Industry namely structured data about technology companies, products, investors, investments and news.

    Initially, the DX Network is meant to be used as a complement to traditional data collection techniques such as purchasing a subscription from a data aggregator or scraping data from the web.

    The three key advantages of acquiring data from the DX Network are as follows:

    1. Real-time access to a wide range of data sources via a single API: data purchased from a DX marketplace is delivered aggregated from the most recent data listed by sellers in standard format (as defined by the marketplace's data model). This makes DX marketplaces particularly suited for use as data sources in live applications.

    2. Semantic queries: moving beyond rigid data queries, the DX Network's semantic query language allows for unfettered access to the knowledge contained in DX marketplaces. It allows for arbitrarily complex—user crafted—data queries against the marketplace's underlying dataset which dramatically speed up data analysis tasks and can be used to reveal previously hidden insights. For convenience, a set of wrapper endpoints are also provided for a more familiar but less flexible interface to marketplace data.

    3. Pay-as-you-go and Pay-per-datapoint: The DX Network inscribes itself in the machine-payable web movement. Instead of having marketplace participants deal with a central authority to collect, manage and deliver data and payments, trust-critical authentication and payment functions are performed using a state channel on the Ethereum blockchain as specified in Chapter 4 of the DX Network's whitepaper. This guarantees that data purchased by consumers hasn't been tampered with, allows consumers to pay for data with single-datapoint precision—paying data sellers directly, bypassing any middlemen—while guaranteeing data sellers collect the correct payment each time their data is hit all without requiring a subscription or any other agreement with a centralized authority.

    By design, the DX Network is a fully open and neutral. It provides the core infrastructure needed for unbiased, secure, efficient and standardized data exchange between data consumers and owners. As such, it makes no assumption about marketplace participant honesty or data quality, taking instead an open market approach: data consumers are able to specify a whitelist or blacklist with their requests to include only certain data sources or exclude specific ones. Combining this mechanism with the marketplace's intrinsic economic incentives to prevent malicious behavior, the overall objective is to move away from central and authorative decisions in favor of crowdsourced reputation systems where individual data consumers are able to choose which data sources they decide to trust or not, on their own terms.

    Finally, as most protocol and infrastructure-layer blockchain projects, the DX Network's source code is publicly available. We encourage our community to make pull requests on GitHub and provide assistance to developers who wish to build applications on top of the DX Network e.g. payment gateways, third party application plugins etc. Do get in touch if you're (thinking of) building one or if you have any comments/suggestions about this documentation.

    Getting started

    Language Version Example
    Python 3 PyPI DX-examples.py

    Install and use the Python library

    1. [Optional] Install Python 3 by following the guide for your choice of OS here.

    2. [Optional] Setup a virtual environment by running:

    Linux/macOS

    python3 -m venv env && source env/bin/activate

    Windows

    python -m venv env && env\Scripts\activate.bat

    3. Install the DX library by running:

    Linux/macOS

    pip3 install DX.py

    Windows

    pip install DX.py

    4. Download the example script from above.

    5. Replace the arguments of DX.wallet.load with a wallet filename and password that has Testnet (Ropsten) DX Tokens and Ethers. Get in touch if you need Testnet DX Tokens or Ethers.

    6. Run the modified script:

    Linux/macOS

    python3 DX-examples.py

    Windows

    python DX-examples.py

    Tweak at will and enjoy!

    Authentication

    Unlike most APIs, the DX Network doesn't use access tokens to authenticate users. Instead, it requires a marketplace buyer or seller to open a payment channel on the Ethereum blockchain to prove their identity and that they have the funds necessary to pay for any potential requests they might make on the network. For data sellers, the Ethereum address used to open the payment channel in which a given set of data was listed for sale is where payments are sent to when any of the data is later purchased on the network.

    The technicalities are detailed in Chapter 4 of the DX Network's whitepaper and are entirely abstracted away from application developers using the provided DX SDKs, which only require the most rudimentary understanding of how Ethereum wallets work. Once the first fiat payment gateways are made available, absolutely no understanding of blockchain technology will be required to use the network.

    Definitions

    Data Models

    On the DX Network, each data marketplace, or DX marketplace, corresponds to a specific knowledge domain e.g. data about the Technology Industry (Tech Industry data), the DX Network's first data marketplace. While all DX marketplaces use the same underlying technology and interface, a given DX marketplace differs from another by defining its own structure, format and semantics corresponding to its specific knowledge domain. These strictly determine the nature of the data buyers and sellers can exchange.

    Each DX marketplace data model is defined through an ontology written using the OWL 2 Web Ontology Language, a W3C standard to define the structure of knowledge for various domains.

    Informally, our data models may be viewed as directed graphs in which the nodes represent either entities or data values and there are two types of edges: those linking entities to other entities (relationships) and those linking entities to data values (data properties).

    A familiarity with the OWL 2 specification is not required to use the APIs, however for completeness we include a brief outline of the OWL representation of our data models for those interested in downloading and exploring them in more depth. Each DX data model conforms to the OWL 2 RL Profile a subset of the full language. Entities are represented as OWL named individuals, the entity types as OWL classes, the relationships between entities as OWL object properties and values are associated with entities using OWL data properties. Data values are typed following the OWL 2 RL Profile utilising a subset of the XML Schema Definition (XSD) types. The XSD base types used in this specification are: integer, positiveInteger, string, boolean and dateTime.

    Initially, the following data model is defined in the DX Network:

    DX Tech Industry Model

    The Tech Industry data model represents the different entities: organizations (e.g. startups, investment firms and news publishers, see OrganizationCategory), articles and products which play or have played a role in today's technology industry, together with their associated properties (such as funding rounds and online presence, see Additional entities).

    The data model can be visualized here and the corresponding Turtle file can be downloaded here.

    For instance, the fact that a public company called Tesla, Inc. (formerly Tesla Motors) was founded on the 1st of July 2003 (source) would be represented by the following set of properties as defined by the Organization entity type of the ontology:

    Data model example

    Where <URN> is the organization's uniform resource name which uniquely identifies Tesla, Inc. on the DX Network.

    The following entity types are defined in the Tech Industry ontology:

    Article

    Subtypes

    BlogPost, News, Review

    Data Properties

    Relationships

    Organization

    Data Properties

    Relationships

    Product

    Data Properties

    Relationships

    Additional entities

    Address

    Data Properties

    Relationships

    Advisor

    Relationships

    AngelList

    Data Properties

    AppStore

    Subtypes

    AppleAppStore, PlayStore

    Data Properties

    AppleAppStore

    Data Properties

    BetaList

    Data Properties

    BlogPost

    Data Properties

    Relationships

    Country

    Data Properties

    Relationships

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:country/.

    Example: urn:dx:tech-industry:country/ad

    Values

    Crunchbase

    Data Properties

    Currency

    Data Properties

    DebtRound

    Data Properties

    Relationships

    Directory

    Subtypes

    AngelList, BetaList, Crunchbase, ProductHunt, StartupTracker

    Data Properties

    EquityCrowdfundingRound

    Data Properties

    Relationships

    EquityRound

    Subtypes

    EquityCrowdfundingRound

    Data Properties

    Relationships

    EquityRoundStage

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:equity-round-stage/.

    Example: urn:dx:tech-industry:equity-round-stage/ipo

    Values

    Facebook

    Data Properties

    Founder

    Relationships

    FundingRound

    Subtypes

    DebtRound, EquityRound, GrantRound, NonEquityCrowdfundingRound, TokenSaleRound

    Data Properties

    Relationships

    GrantRound

    Data Properties

    Relationships

    Image

    Data Properties

    Instagram

    Data Properties

    Investor

    Relationships

    LinkedIn

    Data Properties

    Market

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:market/.

    Example: urn:dx:tech-industry:market/accounting-and-legal

    Values

    MonetaryAmount

    Data Properties

    Relationships

    News

    Data Properties

    Relationships

    NonEquityCrowdfundingRound

    Data Properties

    Relationships

    OnlinePresence

    Subtypes

    AppStore, Directory, Social

    Data Properties

    OrganizationCategory

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:organization:category/.

    Example: urn:dx:tech-industry:organization:category/accelerator

    Values

    OrganizationStatus

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:organization:status/.

    Example: urn:dx:tech-industry:organization:status/active

    Values

    OrganizationType

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:organization:type/.

    Example: urn:dx:tech-industry:organization:type/delisted

    Values

    Person

    Subtypes

    Advisor, Founder, Investor

    Relationships

    PhysicalGood

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:product:type/.

    Example: urn:dx:tech-industry:product:type/hardware

    Values

    Place

    Subtypes

    Address, Country, Region, Subregion

    PlayStore

    Data Properties

    ProductHunt

    Data Properties

    ProductStage

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:product:stage/.

    Example: urn:dx:tech-industry:product:stage/pre-launch

    Values

    ProductType

    Subtypes

    PhysicalGood, Software

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:product:type/.

    Example: urn:dx:tech-industry:product:type/service

    Values

    Region

    Data Properties

    Relationships

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:region/.

    Example: urn:dx:tech-industry:region/africa

    Values

    RevenueModel

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:revenue-model/.

    Example: urn:dx:tech-industry:revenue-model/advertising

    Values

    Review

    Data Properties

    Relationships

    Social

    Subtypes

    Facebook, Instagram, LinkedIn, Twitter, YouTube

    Data Properties

    Software

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:product:type/.

    Example: urn:dx:tech-industry:product:type/desktop-app

    Values

    StartupTracker

    Data Properties

    Subregion

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:subregion/.

    Example: urn:dx:tech-industry:subregion/australia-and-new-zealand

    Values

    TokenSaleRound

    Data Properties

    Relationships

    Twitter

    Data Properties

    UserType

    Possible values are represented as URNs using the prefix urn:dx:tech-industry:user-type/.

    Example: urn:dx:tech-industry:user-type/b2b

    Values

    YouTube

    Data Properties

    DX Tech Industry API

    The DX Tech Industry API provides a familiar interface to the Tech Industry DX marketplace, similar to the APIs traditional Tech Industry data providers tend to offer.

    It trades off query flexibility for familiarity by providing a wrapper over the DX Network's semantic interface, removing the need to understand or use the DX/SPARQL query language.

    Search organizations

    Definition

    GET  https://api-alpha.dx.network/techindustry/organizations

    This endpoint returns a list organization summaries matching the specified query parameters.

    An organization summary consists of a unique identifier (UUID) and basic information about the matching organization.

    The page size is fixed at 100 and switching between pages is possible using the page query parameter.

    Parameters

    Fetch an organization

    Definition

    GET  https://api-alpha.dx.network/techindustry/organizations/:uuid

    Returns all available data for the specified Organization including its Products. The organization's identifier must be specified in the uuid path parameter which can be obtained by doing a search.

    DX Semantic API

    The DX Network stores data in a graph style knowledge base which allows for powerful semantic queries.

    The DX Semantic API offers direct access to all of the DX Network's data properties and relationships across all entities and data models. Queries can be made using a simplified version of the SPARQL query language which is the W3C standard to extract knowledge from semantic graph databases.

    All ontology specific wrapper APIs are built on top of the DX Semantic API. The following endpoints allow for advanced data discovery, analytics as well as enrichment scenarios.

    DX/SPARQL

    DX/SPARQL is a custom version of SPARQL 1.1 that can be used to retrieve knowledge from any of the network's supported knowledge domains. Most features of the SPARQL query language are available in DX/SPARQL, however data modification—the CONSTRUCT query form and the SPARQL 1.1 Update Language—and some niche features such as federated queries are not available.

    The following sections are based on an early, work in progress version of DX/SPARQL. As the development of the DX Network progresses the query language's specification could change.

    DX/SPARQL compared to SPARQL

    DX/SPARQL is a subset of SPARQL with DX Network specific extensions. The main differences are:

    The following prefixes are defined in DX/SPARQL queries:

    PREFIX  rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX  owl: <http://www.w3.org/2002/07/owl#>
PREFIX   dx: <http://dx.network/tech-industry#>

    Any additional prefixes will be ignored, however we plan to lift this restriction as the network grows.

    DX/SPARQL Examples

    Example #1: Find the investors that invested at least $100k in fashion companies.

    SELECT $inv
WHERE {
  $org a dx:Organization ;
    dx:hasMarket <urn:dx:tech-industry:market/fashion> ;
    dx:hasFundingRound $round .

  $round dx:hasFundingRoundInvestor $inv ;
    dx:fundingRoundCurrency <urn:dx:tech-industry:currency/usd> ;
    dx:fundingRoundAmount $amount .

  FILTER ($amount >= 100000)
}

    Example #2: Find B2B or B2G AI companies based in London, UK.

    SELECT $org $name
WHERE {
  $org a dx:Organization ;
    dx:hasMarket <urn:dx:tech-industry:market/ai> ;
    dx:hasHeadquarter $addr ;
    dx:hasUserType $user_type ;
    dx:entityName $name .

  $addr dx:addressCity "London" ;
    dx:hasCountry <urn:dx:tech-industry:country/gb> .

  FILTER (
    $user_type IN (
      <urn:dx:tech-industry:user-type/b2b>,
      <urn:dx:tech-industry:user-type/b2g>
    )
  )
}

    Example #3: Find all Western European companies submittied by the given data sellers.

    SELECT $org
WHERE {
  $region dx:hasSubregion <urn:dx:tech-industry:subregion/western-europe> .
  $country dx:hasRegion $region .
  $hq dx:hasCountry $country .

  $org a dx:Organization ;
    dx:hasHeadquarter $hq .

  WHITELIST (
    "0x02BdaCb2c3BAA8a12D3957f3bd8637d6d2b35f10",
    "0x66D57867A1523dB7165Fc48228CC61b05F363008"
  )
}

    Example #4: Return the second page of all companies that have revenue.

    SELECT $org
WHERE {
  $org a dx:Organization ;
    dx:organizationIsPostRevenue true .
}
PAGE 2

    Example #5: Return five B2B recruitment companies that generate revenue through sales and subscriptions.

    SELECT $org $name
WHERE {
    $org a dx:Organization ;
         dx:organizationIsPostRevenue true ;
         dx:hasUserType <urn:dx:tech-industry:user-type/b2b> ;
         dx:hasMarket <urn:dx:tech-industry:market/hr-and-recruitment> ;
         dx:hasRevenueModel $revenue_model ;
         dx:entityName $name .

    FILTER (
        $revenue_model IN (
           <urn:dx:tech-industry:revenue-model/sales>,
           <urn:dx:tech-industry:revenue-model/subscription>
        )
    )
}
PAGE 1 SIZE 5

    Search by semantic query

    Definition

    GET  https://api-alpha.dx.network/semantic/search

    This endpoint can be used to retrieve knowledge embedded in the network's relationships and data fields using the network's simplified version of SPARQL called DX/SPARQL. DX/SPARQL only supports the SELECT query form and restricts some advanced SPARQL features.

    In case multiple versions of a relationship or data property are available as a response to a given DX/SPARQL query, the network automatically returns the most recent value listed across sellers, in accordance with the caller's whitelist/blacklist.

    Solutions which match the patterns described in the query's WHERE clause are returned in JSON format according to the SPARQL Query Results JSON Format specification.

    Parameters

    Fetch by identifier

    Definition

    GET  https://api-alpha.dx.network/semantic/fetch

    This endpoint allows for fetching the properties associated with an entity identified by its URN. Properties can be any of the data properties and/or relationships which are defined in the corresponding ontology. The endpoint returns exact data values for data properties and the URNs which identify the entities on the other side of the relationships for relationships.

    Parameters

    Errors

    The DX Network API uses the following HTTP error codes:

    Error Code Reason
    400 Bad Request — Your request is invalid.
    401 Unauthorized — Your API key is wrong.
    402 Payment Required — Initial deposit required.
    404 Not Found — The specified endpoint could not be found.
    405 Method Not Allowed — You tried to access an endpoint with an invalid method.
    406 Not Acceptable — You requested a format that isn't JSON.
    Shell