openapi: "3.0.1"

info:
  title: hyScore Contextual Data API 
  description: |
    A lean Software as a Service approach to extracting contextual data for multiple use cases.
    # Introduction 
    No matter if you want to integrate our Contextual Data API into your website with JavaScript or call it from your backend systems written in 
    Java, C#, Python, or any other language. Our Contextual Data API is platform and programming language independent and can be integrated in 
    any system in just a few minutes. It's as simple as sending us a HTTP POST request and receiving the data in JSON format.

    ![integration image](https://s3-eu-west-1.amazonaws.com/hyscore-api-documentation/integration_diagram.png "Integration with hyScore")
    
    # How can I get an API-Key?
    Just get in touch with us and request a personal API-Key via the web form. As an alternative, you can write us an email to info@hyscore.io.
    We offer 10.000 API requests per month for free, so that you can try out our service without any costs or risks.
    # Use cases
    Most of our customers uses cases can be divided into two different scenarios: real-time and bulk processing.
    For both the integration is exactly the same, what differs is how the data is "collected" and used.
    
    An example for a real-time scenario is a contextual video player
    (you can see this example on our website at https://hyscore.io/use-cases/contextual-video ).
    With just a few lines of JavaScript on your website, you call our API and use the returned contextual data to get the right content
    into your video player. 

    Wanting to categorize and catalog your website inventory, is an example for bulk processing.
    You might send us several thousand or even millions of URLs. As this will take some time to process and analyze,
    let's say you "come back" 15 minutes later to pick up the results. The nice thing is that picking up the results,
    is just sending us the same request again. This keeps the implementation effort for the integration very low.

  version: "3.0"
  contact:
    name: hyScore.io
    url: https://www.hyScore.io
    email: contact@hyscore.io
  x-logo:
    url: 'https://s3-eu-west-1.amazonaws.com/hyscore-api-documentation/logo.png'
    
servers:
- url: https://api.hyscore.io/v3/url

security:
  - API-Key: []

tags:
  - name: request
    description: "Our API offers one simple endpoint at https://api.hyscore.io/v3/url to make your request."

paths:
  /url:
    post:
      tag: request
      summary: url
      requestBody:
        description: "The URL to be analyzed and optional config parameters"
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestConfig'
      responses:
        200:
          description: "The contextual data of the provided URL"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      x-code-samples:
        - lang: 'Simple Request'
          source: |
            {
              // "url" is the only mandatory field, all others can be omitted
              "url": "https://www.hyscore.io"
            }
        - lang: 'JavaScript'
          source: |
            function getData() {
              // configure the request
              var settings = {
                "async": true,
                "crossDomain": true,
                "url": "https://api.hyscore.io/v3/url",
                "method": "POST",
                "headers": {
                  "x-api-key": YOUR API KEY,
                  "content-type": "application/json"
                },
                "data": {
                  "url": "http://example.com"
                }
              }
              // send the request
              $.ajax(settings).done(function(response) {
                // extract the contextual data from 'response'
              });
            }
        - lang: 'Python'
          source: |
            import requests
            import json

            url = "http://api.hyscore.io/v3/url"
            headers = {
                'x-api-key': "YOUR_API_KEY",
                'Content-Type': "application/json"
            }
            payload = json.dumps({"url": "YOUR_URL"})
            response = requests.request("POST", url, data=payload, headers=headers)
            print(response.text)
        - lang: 'Java'
          source: |
            // create a POST request
            URL url = new URL("https://api.hyscore.io/v3/url");
            HttpURLConnection con = (HttpURLConnection) url.openConnection();
            con.setRequestMethod("POST");

            // set the header information
            con.setRequestProperty("x-api-key", YOUR API KEY);
            con.setRequestProperty("Content-Type", "application/json");

            // set the body information
            String body = "url=" + URLEncoder.encode("http://example.com", "UTF-8");

            con.setDoOutput(true);
            DataOutputStream out = new DataOutputStream(con.getOutputStream());
            out.writeBytes(body);
            out.flush();
            out.close();

            // send request
            int status = con.getResponseCode();

            // read response
            InputStreamReader reader = new InputStreamReader(con.getInputStream());
              BufferedReader in = new BufferedReader(reader);
            String inputLine;
            StringBuffer content = new StringBuffer();
            while ((inputLine = in.readLine()) != null) {
                content.append(inputLine);
            }
            in.close();
            con.disconnect();

            System.out.println(status);  // the http status code of the request
            System.out.println(content); // the contextual data as json
  
components:
  schemas:
    RequestConfig:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: "The URL to be analyzed. Note that the protocol ('http://' or 'https://') has to be included."
          example: "https://www.hyscore.io"
        getText:
          type: boolean
          description: "Optional parameter. Defines if the API should return the extracted website text. Default is 'false'."
          default: false
        imageDiv:
          type: object
          additionalProperties: true
          example: {'class':'main-image'}
          description: "Optional parameter. Instead of letting the system automatically choose the appropriate image, you can enter a css selector of the image div that should be used."
        articleDiv:
          type: object
          additionalProperties: true
          example: {'id':'article-news'}
          description: "Optional parameter. Allows you to specify which part of the website should be analyzed, instead of the whole website."
        customData:
          type: object
          additionalProperties: true
          example: {'uuid':'975b4322-dcde-4de7-886d-c082f3743b21'}   
          description: "Optional parameter. Can contain any custom information, identifier, etc. We don't save this information, but return it in the response so that you e.g. can enrich your user profiles and enhance data sets."
    
    Response:
      type: object
      required:
      - status
      properties:
        status:
          description: "The status tells, if the request was successful, the analyis is still in progress, or if there was an error."
          oneOf:
            - $ref: '#/components/schemas/Status_1_Successful'
            - $ref: '#/components/schemas/Status_0_NoDataYet'
            - $ref: '#/components/schemas/Status_10_Incomplete'
            - $ref: '#/components/schemas/Status_11_Error'
            - $ref: '#/components/schemas/Status_12_Error'
            - $ref: '#/components/schemas/Status_13_Error'
            - $ref: '#/components/schemas/Status_14_Error'
            - $ref: '#/components/schemas/Status_15_Error'
            - $ref: '#/components/schemas/Status_16_Error'
            - $ref: '#/components/schemas/Status_17_Error'
            - $ref: '#/components/schemas/Status_99_Error'
          example:
            code: 1
            message: "All seems well."
            
        url:
          type: string
          description: "Origin / Full URL of the analyzed site."
          example: "https://www.hyScore.io"
        tld:
          type: string
          description: "The Top Level Domain of the analyzed URL."
          example: "hyscore.io"
        result:
          $ref: '#/components/schemas/Result'
        
    Status_1_Successful:
      type: object
      description: "Analyzing the URL was successful. All contextual data is included in the response."
      properties:
        message:
          type: string
          example: "All seems well."
        code:
          type: integer
          example: 1
    Status_0_NoDataYet:
      type: object
      description: "Analyzing the URL is in progress. The contextual analysis data is not present yet. Request the same URL again or wait some time. A full result is normally provided with th 2nd or 3rd request (100ms to 400ms)."
      properties:
        message:
          type: string
          example: "No data yet."
        code:
          type: integer
          example: 0
    Status_10_Incomplete:
      type: object
      description: "Analyzing the URL was successful, but something went wrong determining a correct category. All contextual data is present apart from the categories. Request the same URL again or wait some time until the category has been determined."
      properties:
        message:
          type: string
          example: "Incomplete"
        code:
          type: integer
          example: 10
    Status_11_Error:
      type: object
      description: "Target URL not reachable: Crawler could not create a connection to the provided URL, usually a time-out/connection error. If a website did not respond within 10 seconds the request will time-out."
      properties:
        message:
          type: string
          example: "Target URL not reachable"
        code:
          type: integer
          example: 11
    Status_12_Error:
      type: object
      description: "URL blocked by robots.txt: Website disallows crawling. This can be fixed by whitelisting the hyScore.io user-agent. Read the hyScore.io crawler information on the website hyScore.io."
      properties:
        message:
          type: string
          example: "URL blocked by robots.txt"
        code:
          type: integer
          example: 12
    Status_13_Error:
      type: object
      description: "Target URL returned non 200 HTTP Code: Provides additional field 'httpErrorCode' with RFC standard codes, only if it's not explicitly covered by another error code (I.e. 429 – too many requests), usually a 4xx/5xx error."
      properties:
        message:
          type: string
          example: "Target URL returned non-200 HTTP Code"
        code:
          type: integer
          example: 13
        httpErrorCode:
          type: integer
          example: 418
    Status_14_Error:
      type: object
      description: "Unparseable body: Website body could not be decoded, usually the fault of an illegal charset."
      properties:
        message:
          type: string
          example: "Unparseable body"
        code:
          type: integer
          example: 14
    Status_15_Error:
      type: object
      description: "Empty body: Website was crawled successfully, but has no body."
      properties:
        message:
          type: string
          example: "Empty body"
        code:
          type: integer
          example: 15
    Status_16_Error:
      type: object
      description: "Unknown host: Crawler could not resolve the domain, this usually means the domain does not exist and is not reachable."
      properties:
        message:
          type: string
          example: "Unknown host"
        code:
          type: integer
          example: 16
    Status_17_Error:
      type: object
      description: "Too many requests: Crawler was blocked by host because it sent to many requests (HTTP error code 429). This can be fixed by whitelisting the crawler.Read the hyScore.io crawler information on the website hyScore.io."
      properties:
        message:
          type: string
          example: "Too many requests"
        code:
          type: integer
          example: 17
    Status_99_Error:
      type: object
      description: "Problematic URL: Technical difficulties while crawling this URL."
      properties:
        message:
          type: string
          example: "Problematic URL"
        code:
          type: integer
          example: 99
    
    Result:
      type: object
      properties:
        metaKeywords:
          type: array
          items:
            type: string
          description: "The meta keywords of the URL set by its publisher (not weighted)."
        description:
          type: string
          description:  "The description of the URL set by its publisher."
        headings:  
          $ref: '#/components/schemas/Headings'
        text:
          type: string
          example: ''
          description: "The extracted text of the URL. This ouptut needs to be activated in the request via 'getText=true'"
        weightedKeyword:
          type: array
          items:
            $ref: '#/components/schemas/WeightedKeyword'
          description: "Contains the keywords/entities extracted from the input. Keywords are displayed in their normalized form."
        imageUrl:
          type: string
          example: 'https://hyscore.io/image.png'
          description: "URL of the article image if available. Either chosen automatically, or via the imagedivid request parameter."
        customData:
          type: object
          additionalProperties:
            type: string
          description: "Returns the same data that was send in the 'customData' parameter."
        sentiment:
          type: number
          example: 0.270456
          description: "The sentiment of the text. It has a value between +1 (perfect), 0 (neutral) and -1 (poor, negative)."
        categories:
          $ref: '#/components/schemas/Categories'
        language:
          type: string
          example: en
          description: "The language of the given text is determined automatically by the system."
        textLength:
          type: integer
          example: 5164
          description: "The length of the analyzed text."
        debug:
          type: string
          example: Text field deactivated.
          description: "A field that gives more insights. It is not intented for automatical processing, but rather as a help for developers when integrating our API, or for analyzing behaviors of the API."
        
    Headings:
      type: array
      description: "The content of the headers of the website."
      items:
        type: object
        properties:
          tag:
            type: string
            example: h1
            description: The html heading tag, for example h1.
          content:
            type: string
            example: Some Header
            description: The content of the html heading tag.
    WeightedKeyword:
      type: object
      properties:
        surfaceForms:
          type: array
          items:
            type: string
            example: Manchester City
        frequency:
          type: integer
          example: 42
          description: How often the word is mentioned in the analyzed text.
        type:
          type: string
          example: SoccerClub
        name:
          type: string
          example: Manchester City F.C.
        weight:
          type: number
          example: 4.242
    Categories:
      type: object
      properties:
        hyscore:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: sport_soccer
              wheight:
                type: number
                example: 68.231
        iab:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
                example: Sports
              v1:
                type: string
                example: IAB17-44
              v2:
                type: integer
                example: 533
              weight:
                type: number
                example: 68.231
  
  securitySchemes:
    API-Key:
      type: apiKey
      description: "The API authorizes requests through an API key in your header. Enter your hyScore API Key here. If you don't have an API key yet, contact us for a free tier API key at contact@hyscore.io."
      name: x-api-key
      in: header