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-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

JobViz API Technical Information

Introduction

Web Service Endpoint

Request Content Types

Job Post Parameter

Response Structure

Getting Started

Authentication

Resource Listing

Skills

Response

Roles

Response

Sectors

Response

Domains

Response

Category

Response

category-subcategory

Response

Visualization-file

Response

Visualization-inline

Response

Optional Visualization Request Parameters

Visualization Anomalies

No Job Content

No Segments Extracted

Too Few Segments Extracted

Visualization Exceptions

Colour Schemes