JobViz API Technical Information

Introduction

The JobViz Web Service is accessed via a simple RESTful API. Each request is independent of other requests and no client state is transferred or retained by the server between requests. Each request for disaggregated content is made via the HTTP post method, the body of which must contain the job description and in the case of a visualization request, may contain any of the optional parameters to define the visualization preferences. Each request must present the correct authentication credentials to the server.

Web Service Endpoint

All JobViz resources will sit under the web service endpoint:

https://bctresourcing.co.uk/jobviz/api/v1

Request Content Types

JobViz expects requests to have one of the following content types:

multipart/form-data

application/json

Job Post Parameter

The job description is passed as plain text as a post parameter with each HTTP Post request.

A post request should aways contain the job content in the request body in the job post paramter. The job title can be prepended to the job body in the job attribute if desired, but is not usually necessary.

Response Structure

JobViz issues a JSON formatted response. For all corresponding HTTP post requests, the response adopts the following format with the requested information contained within the data property:

{
  "program": "jobviz",
  "version": "1.0.0",
  "timestamp": 1589369170,
  "status": "success",
  "code": 200,
  "message": "skills extract successful - ",
  "data": {
    "skills": [
      "Investment Banking",
      "Financial Modelling",
      "M&A",
      …,
    ]
  }
}

The code attribute of the response specifies the HTTP status code with 200 indicating that the server has successfully and completely processed the request. Other status codes indicate exception conditions. The message attribute will provide further detail in these cases. The timestamp gives the unix timestamp that the server processed the request. The status will be either success or error.

Some Possible Response States
code status Description
200 success request successful
204 success no visualization content produced from request
400 error Invalid parameter value in request...
401 error unauthorized resource
404 error resource not found
405 error method not allowed

Once the data JSON attribute is decoded from the response, the data can be parsed and used as needed by any client application.


Getting Started

To gain access to the JobViz web service you will need to request an account to be set up. If you do not currently have an account you may request one here.

After our admin team has created an account you will receive an email instructing you to set up a password. You will need to do this within 24 hours of account creation.

Authentication

Authentication is achieved via standard HTTP Basic Authentication. Authentication is required on each and every request to JobViz. Each request to JobViz must therefore populate the Authorization field in the HTTP header. This would be constructed from your username and password according to the HTTP basic authentication standard.

Resource Listing

To see an up to date list of the resources provided by the web service issue a get request to the root web service endpoint.

GET /

Resource Listing
HTTP Method Resource Description
GET / List the available resources provided by this web service
POST /skills Derive the skills from a submitted job description in descending order of significance
POST /roles Derive the role names/job titles from a submitted job description in descending order of significance
POST /sectors Derive the industry sectors spanned by a submitted job description in descending order of significance
POST /domains Derive the domains of work spanned by a submitted job description in descending order of significance along with their relative percentage significance
POST /category Categorize the submitted job by category and sub-category
POST /visualization-file Generate a visualization based on the posted job description and return it in standard graphics file format in the response. Additional post fields configure type and style on the visualization
POST visualization-inline Generate a visualization based on the posted job description and return it as a Base64 encoded image embedded in an HTML img tag in the response. Additional post fields configure type and style on the visualization

Skills

POST /skills

Parameter : Job

The skills resource will extract professional skills from the job text.

Response

The skills are returned as a skills attribute within the data property of the JSON response string in order of precendence. The skills attribute is expressed as an array of strings.

{
  …
  "code": 200,
  "message": "skills extract successful - ",
  "data": {
    "skills": [
      "Investment Banking",
      "Financial Modelling",
      "M&A",
      …,
    ]
  }
}

Roles

POST /roles

Parameter : Job

The roles resource will extract professional roles (job titles) from the job text.

Response

The roles are returned as a roles attribute within the data property of the JSON response string in order of relevance. The roles attribute is expressed as an array of strings.

{
  …
  "code": 200,
  "message": "roles extract successful - ",
  "data": {
    "roles": [
      "Marketing Specialist",
      "Advertising Executive",
      "Marketeer",
      …,
    ]
  }
}

Sectors

POST /sectors

Parameter : Job

The sectors resource will determine which industry sectors the submitted job text spans.

Response

The sectors are returned as a sectors attribute within the data property of the JSON response string in order of relevance. The sectors attribute is expressed as an array of strings.

{
  …
  "code": 200,
  "message": "sectors extract successful - ",
  "data": {
    "sectors": [
      "Marketing, advertising and PR",
      "Sales",
      "Media and Internet",
      …,
    ]
  }
}

Domains

POST /domains

Parameter : Job

The domains resource will assign the submitted job text to areas of work, or work domains and return the results along with percentage distribution within each domain.

Response

The domains are returned as a domains array attribute within the data property of the JSON response string. The domains array attribute is expressed as an array of JSON objects. Each object is made up of two key/value pairs domain and pct.

{
  ...,
  "status": "success",
  "code": 200,
  "message": "Domains extract successful - ",
  "data": {
    "domains": [
      {
        "domain": "software development",
        "pct": "50.0"
      },
      {
        "domain": "analysis",
        "pct": "50.0"
      },
    ]
  }
}

Category

POST /category

Parameter : Job

The category resource categorises the submitted job text assigning it to a single job category and a more specific subcategory where possible.

Response

The category and subcategory are returned as a JSON object within the data property of the JSON response string.

{
  ...,
  "status": "success",
  "code": 200,
  "message": "Category extract successful - ",
  "data": {
    "category": "Information technology",
    "subcategory": "software development",
    "classification": "it"
  }
}

category-subcategory

GET /category-subcategory

The category-subcategory resource provides a listing of the latest category subcategory data structure within Jobviz. Although the content items once listed are unlikely to change, new items will appear from time to time due to new machine learning cycles adding to the inbuilt knowledge graph. It should be noted that the same subcategory maybe attached to more than one category.

Response

The categories are returned as an array within the data property of the JSON response string. The subcategories are nested arrays within this.

{
  ...,
  "status": "success",
  "code": 200,
  "message": "Hierarchy of categories and sub-categories",
  "data": {
    "finance": [
      "Accountancy, banking and finance",
      "accounting",
      "banking",
      "finance",
      "fintech",
      "insurance"
    ],
    "management": [
      "Business, consulting and management",
      "consultancy",
      "electronic records management",
      "enterprise resource planning",
      "health and safety",
      "it architecture",
      "management",
      "project management"
    ],
    ...,
  ...,
}

Visualization-file

POST /visualization-file

Parameter(s) : Job, Optional Visualization Request Parameters.

Post to this resource to disaggregate, generate a visualization and receive it in graphics file format in the response. This method is best for including the visualization in a variety of documents and also gives best page load speeds for web pages that link to it and for boosting SEO of pages. By including any selection of the Optional Visualization Request Parameters the visualization can be extensively customized to the individual specification. Leaving these options as their defaults will generate a donut visualization where the work domains are coloured according to JobViz defined settings.

Response

For a successfully generated visualization the response will feature a key value pair in the data JSON attribute with the key being the file type and the value being the file contents. Under certain circumstances where it is not possible to generate a visualization the response will be as defined in Visualization Anomalies or Visualization Exceptions.

{
  ...,,
  "status": "success", 
  "code": 200, 
  "message": "visualization complete", 
  "data": {
    "png": "iVBORw0KGgoAAAANSUhEUgAACWAAA...
  }
}

Visualization-inline

POST /visualization-inline

Parameter(s) : Job, Optional Visualization Request Parameters.

Post to this resource to disaggregate, generate a visualization and receive it as a Base64 encoded image embedded in an HTML image tag. This allows the image to be included directly in a web page. By including any selection of the Optional Visualization Request Parameters the visualization can be extensively customized to the individual specification. Leaving these options as their defaults will generate a donut visualization where the work domains are coloured according to JobViz defined settings.

Response

For a successfully generated visualization the response will contain the direct representation of the HTML tag with the base64 encoded image data embedded within it. Under certain circumstances where it is not possible to generate a visualization the response will be as defined in Visualization Anomalies or Visualization Exceptions.


Optional Visualization Request Parameters

Parameter Applies to Allowed Default Description
type N/A donut, treemap, skillstreemap, radar, skillsradar, wordcloud, densewordcloud donut Type of visualization to generate
min_segments all positive integer 5 Minimum number of disagregated skill/domain segments required to generate visualization
width all positive integer 500 Width in pixels of generated image
height treemaps, wordclouds positive integer 500 Height in pixels of generated image
legend donuts No, False, Yes, True False Display a legend in the visualization
legend_title donuts No, False, Yes, True No Display a legend title in the visualization
pcts donuts No, False, Yes, True True Display percentages on the legend in the visualization
inner_labels donuts No, False, Yes, True False Display domain lables on the inner slices of a donut
colour donuts, treemaps, wordclouds A JobViz defined colour scheme By domain, or Blue A set of colours used by some visualizations as listed here
fill_colour radars Any RGB x11 colour name or hex Blue A fill colour used by some visualizations
background_colour radar, wordclouds Any RGB x11 colour name or hex Silver A background colour used by some visualizations
edge_colour donuts, radars, treemaps Any RGB x11 colour name or hex White An edge colour used by some visualizations

Visualization Anomalies

There are potentially three visualization anomalies resulting from a posted request where there will be no visualization data returned in the reponse. The HTTP code is set to 204 in these cases to enable a client to trap such a response and the data attribute will be empty.

No Job Content

This response results when empty job content has been posted in the request.

{
  "code": "204",
  "data": {},
  "status": "success",
  "message": "No textual content provided.",
...
}

 

No Segments Extracted

This response results when job content was included in the post request but no skills or work domains could be extracted. This may occur when the job text is unusually short.

{
"code": "204",
"data": {},
"status": "success",
"message": "No skills/Domains extracted from the requested content",
...
}

 

Too Few Segments Extracted

This response results when job content was included in the post request and at least one skill or domain have been disaggregated from the text but the number is below the minimum threshold set in the min_segments post request parameter.

{
  "code": "204",
  "data": {},
  "status": "success",
  "message": "Not enough skills/domains extracted from the passed text.",
  ...
}

Visualization Exceptions

A response will be returned to the client with HTTP code 400 and status attribute set to error in the case where any of the optional request paramters are posted with an invalid value.

{
  "code": "400",
  "data": {},
  "status": 'error',
  "message": "Invalid parameter value in request. The width parameter must be type int.",
  ...
}

Colour Schemes

The below colour schemes may be passed as the colour parameter to define a colour scheme that the generated visualization adopts for those visualizations that assign a colour scheme during their construction. 

  • Blue
  • Green
  • Orange
  • Purple
  • Pink
  • Red
  • Copper
  • Pastel1
  • Pastel2
  • Accent
  • Paired
  • Grey
  • Gray
  • Binary
  • Bone
  • Cool
  • Coolwarm
  • Hot
  • Plasma
  • Magma
  • Seismic
  • Spectral
  • Prism
  • Rainbow
  • Jet
  • Spring
  • Summer
  • Autumn
  • winter
  • Terrain
  • Ocean
  • Twilight