Document API integration

The Documents API grants access to an extensive collection of innovation-related publications, including news, patents, scientific papers, standards, research projects, and project descriptions.
Learn more about these publications in this article.

By integrating the Documents API into your application, you can retrieve structured, filtered content based on specific search queries. Designed for applications that rely on diverse, high-quality publications, this API helps analyze trends, track competitor developments, and monitor advancements across various fields.

The API returns data in JSON format.

‍

Getting started 

Before integrating the Documents API, you must authenticate and generate a token. You can test the API using the API Demo page, where you can also download a JavaScript demo app to test it directly in your browser.

‍

Make Requests

To interact with the API, you must send HTTP GET or POST requests to the API endpoint using the default content type. Every request needs a token.

• API Endpoint: https://api.mapegy.com
• Content-Type: application/x-www-form-urlencoded
• Route: /Documents/?q=

Required parameter: q. Defines the query structure for retrieving documents.
Find an example below. You can also learn more about the q parameter here. 

{
    "format_version": "1.6.0",
    "data": {
        "semantic": "",
        "topics": [
            [
                "artificial intelligence",
                "deep learning"
            ]
        ],
        "not_topics": [],
        "organizations": [],
        "not_organizations": []
    }
}

‍

Optional Parameters:

• topic_id: Filter results by related topic IDs (comma-separated values).
• player_id: Filter results by related player IDs (comma-separated values).
• document_id: All documents that match this ID(s) will be returned, ignoring all other filters, and no matter how well they match the query. This can be used to update KPIs of bookmarked documents.
• type: Restrict results to specific document types (e.g., NEWS, NEWS__STARTUP, NEWS__FORECAST). Just add them as comma-separated values. 
• highlight: Set 'true' to highlight matched keywords in title and abstract with <mark>keyword</mark> (returns HTML). Default: 'false' (returns TEXT).
• country_code: Add two letter country codes to focus on specific patent offices. Separate values by commas. 
• language_code: Add language code to filter by language (e.g. EN). 
• date_from: Set earlier date using the following format: YYYY-MM-DD. 
• date_to: Set latest date using the following format: YYYY-MM-DD. 
• days: Number of past days within which the item was integrated into the InnovationGraph.
• limit: Restricts the number of documents, just enter a number from 1 to 30.‍
• include: Specifies which response fields to retrieve. Simply list the desired response fields, separated by commas. To view all available fields, run a query without specifying this parameter.

‍

Example: Access the Documents API with a valid token:

• Route: /Documents/?q=
• Method: GET or POST
• Content-Type: application/x-www-form-urlencoded
• Mandatory parameters: q (query), token
• Optional parameters used: type, country_code, date_from
• Example GET request:
  Documents/?q=%7B%22format_version%22%3A%221.6.0%22,%22data%22%3A%7B%22semantic%22%3A%22%22,%22topics%22%3A%5B%5B%22artificial%20intelligence%22,%22deep%20learning%22%5D%5D,%22not_topics%22%3A%5B%5D,%22organizations%22%3A%5B%5D,%22not_organizations%22%3A%5B%5D%7D%7D&token=fr9Ch_2BDFI-rBR6edo0Lb-0JRVP6lBb5Fb7p4FYND0Xnlk_2NpNNcJ1IAYlO3SL&type=PATENT&country_code=US&date_from=2024-01-01 ‍
• ‍Example response:
  

[
  {
    "title": "Method and system for adaptive virtual broadcasting of digital content",
    "doc_id": 192430740,
    "topics": {
      "SECTOR": [
        {
          "term": "IT & Telecommunications",
          "topic_id": 1487261,
          "score_relevance": 1.709
        }
      ],
      "SCIENCE": [
        {
          "term": "Computer Networks and Communications",
          "topic_id": 5782254,
          "score_relevance": 1.709
        },
        {
          "term": "Media Technology",
          "topic_id": 5782110,
          "score_relevance": 1.6
        },
        {
          "term": "Hardware and Architecture",
          "topic_id": 5782163,
          "score_relevance": 0.608
        }
      ],
      "INDUSTRY": [
        {
          "term": "Communication",
          "topic_id": 1487182,
          "score_relevance": 1
        }
      ],
      "TECHNOLOGY": [
        {
          "term": "Digital communication",
          "topic_id": 1487227,
          "score_relevance": 1
        }
      ]
    },
    "abstract": "The virtual broadcast system of the present invention optimizes the routing of digital content among nodes along overlay networks that are dynamically reconfigured based upon forecasts of...",
    "doc_type": "PATENT",
    "web_links": {
      "homepage": "https://worldwide.espacenet.com/patent/search?q=PN=US2016192029A1"
    },
    "patent_meta": {
      "events": [],
      "granted": "true",
      "publn_nr": [
        "US2016192029A1",
        "US9769536B2"
      ],
      "epodoc_nr": "14848268",
      "inventors": [
        {
          "person_name": "Bergstrom, Mattias",
          "person_address": "Puerto de la Cruz",
          "person_ctry_code": "ES",
          "person_name_orig_lg": "Bergstrom, Mattias"
        }
      ],
      "applicants": [
        {
          "person_name": "Bergstrom, Mattias",
          "person_address": "Puerto de la Cruz",
          "person_ctry_code": "ES",
          "person_name_orig_lg": "Bergstrom, Mattias"
        },
        {
          "person_name": "SYSTEM73, INC.",
          "person_address": "Dallas,TX",
          "person_ctry_code": "US",
          "person_name_orig_lg": "SYSTEM73, INC."
        }
      ],
      "prior_date": "2014-12-26",
      "country_code": "US",
      "patent_office": "US",
      "docdb_family_id": 55066402,
      "docdb_family_size": 18,
      "nb_citing_docdb_fam": 75
    },
    "doc_sub_type": [],
    "expert_names": [
      "Mattias, Bergstrom"
    ],
    "doc_timestamp": "2015-09-08 00:00:00 UTC",
    "language_code": "EN",
    "score_relevance": 0.3799,
    "player_sub_types": [
      "COMPANY",
      "INVENTOR"
    ],
    "web_links_broken": {},
    "inserted_timestamp": "2018-01-15 10:18:33 UTC",
    "organization_names": [
      "System73, Inc."
    ]
  }
]

‍