{"_id":"5b3a7fb938c5f700033508ab","category":"5b3a7fb938c5f7000335089e","parentDoc":null,"project":"55e767022942b837005467a2","user":"55e765965d36b32b00256428","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T16:54:41.436Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"You're reading the documentation for the **v2.6** SkillsEngine API. This version includes the addition of a new data element -- Knowledge Subdomains -- to Profiler and Warrior, as well as a host of under-the-hood improvements and enhancements to our scoring algorithms.","excerpt":"","slug":"new-in-version-2","type":"basic","title":"New in Version 2.6","__v":0,"childrenPages":[]}

New in Version 2.6


You're reading the documentation for the **v2.6** SkillsEngine API. This version includes the addition of a new data element -- Knowledge Subdomains -- to Profiler and Warrior, as well as a host of under-the-hood improvements and enhancements to our scoring algorithms.
You're reading the documentation for the **v2.6** SkillsEngine API. This version includes the addition of a new data element -- Knowledge Subdomains -- to Profiler and Warrior, as well as a host of under-the-hood improvements and enhancements to our scoring algorithms.
{"_id":"5b3a7fb938c5f700033508ac","category":"5b3a7fb938c5f7000335089e","user":"55e765965d36b32b00256428","parentDoc":null,"project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-02T21:15:48.547Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The SkillsEngine API requires token-based authentication before requests can be made of any API endpoints.\"\n}\n[/block]\nWhen you sign up to use SkillsEngine, you are provided with a `client_id` and `client_secret`. These two keys allow you to authenticate against our `/api/token` endpoint and receive an `access_token`. This token will be required for all subsequent requests against any SkillsEngine endpoints (unless otherwise specified).\n\nIf you are building a server-side application, it should handle this authentication flow over SSL using a JSON credentials payload.\n\nHere's an example of authenticating with SkillsEngine using the Ruby programming language:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'rest-client'\\nrequire 'json'\\n\\nclient_id = '4ea1b...'\\nclient_secret = 'a2982...'\\n\\nresponse = RestClient.post 'https://api.skillsengine.com/api/token', {\\n  grant_type: 'client_credentials',\\n  client_id: client_id,\\n  client_secret: client_secret\\n}\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nAfter that you'll have the access token in the response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"access_token = JSON.parse(response)[\\\"access_token\\\"]\\n# => 'c4739...'\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nAnd then, you can request access to protected resources. Unlike the previous version of the API, you no longer need to provide an Accept header. Instead, the version is passed in the URL path. The Authorization header with a Bearer token is still required, and should use the `access_token` from above:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# e.g.\\nRestClient.post 'https://api.skillsengine.com/v2/competencies/analyze',\\n  { \\n    'Authorization' => \\\"Bearer #{access_token}\\\",\\n    'Content-Type' => \\\"application/json\\\"\\n  }\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Ensure you are providing a **Content-Type** header with the value **application/json**. While many REST code libraries append this header automatically, if you are operating at a lower-level, or using a library that doesn't, you will need to specify this header yourself, otherwise you may get an empty result response.\"\n}\n[/block]","excerpt":"This page will help you get authenticated with the v2 SkillsEngine API.","slug":"authentication","type":"basic","title":"Authentication","__v":0,"childrenPages":[]}

Authentication

This page will help you get authenticated with the v2 SkillsEngine API.

[block:callout] { "type": "warning", "body": "The SkillsEngine API requires token-based authentication before requests can be made of any API endpoints." } [/block] When you sign up to use SkillsEngine, you are provided with a `client_id` and `client_secret`. These two keys allow you to authenticate against our `/api/token` endpoint and receive an `access_token`. This token will be required for all subsequent requests against any SkillsEngine endpoints (unless otherwise specified). If you are building a server-side application, it should handle this authentication flow over SSL using a JSON credentials payload. Here's an example of authenticating with SkillsEngine using the Ruby programming language: [block:code] { "codes": [ { "code": "require 'rest-client'\nrequire 'json'\n\nclient_id = '4ea1b...'\nclient_secret = 'a2982...'\n\nresponse = RestClient.post 'https://api.skillsengine.com/api/token', {\n grant_type: 'client_credentials',\n client_id: client_id,\n client_secret: client_secret\n}", "language": "ruby" } ] } [/block] After that you'll have the access token in the response: [block:code] { "codes": [ { "code": "access_token = JSON.parse(response)[\"access_token\"]\n# => 'c4739...'", "language": "ruby" } ] } [/block] And then, you can request access to protected resources. Unlike the previous version of the API, you no longer need to provide an Accept header. Instead, the version is passed in the URL path. The Authorization header with a Bearer token is still required, and should use the `access_token` from above: [block:code] { "codes": [ { "code": "# e.g.\nRestClient.post 'https://api.skillsengine.com/v2/competencies/analyze',\n { \n 'Authorization' => \"Bearer #{access_token}\",\n 'Content-Type' => \"application/json\"\n }", "language": "ruby" } ] } [/block] [block:callout] { "type": "warning", "body": "Ensure you are providing a **Content-Type** header with the value **application/json**. While many REST code libraries append this header automatically, if you are operating at a lower-level, or using a library that doesn't, you will need to specify this header yourself, otherwise you may get an empty result response." } [/block]
[block:callout] { "type": "warning", "body": "The SkillsEngine API requires token-based authentication before requests can be made of any API endpoints." } [/block] When you sign up to use SkillsEngine, you are provided with a `client_id` and `client_secret`. These two keys allow you to authenticate against our `/api/token` endpoint and receive an `access_token`. This token will be required for all subsequent requests against any SkillsEngine endpoints (unless otherwise specified). If you are building a server-side application, it should handle this authentication flow over SSL using a JSON credentials payload. Here's an example of authenticating with SkillsEngine using the Ruby programming language: [block:code] { "codes": [ { "code": "require 'rest-client'\nrequire 'json'\n\nclient_id = '4ea1b...'\nclient_secret = 'a2982...'\n\nresponse = RestClient.post 'https://api.skillsengine.com/api/token', {\n grant_type: 'client_credentials',\n client_id: client_id,\n client_secret: client_secret\n}", "language": "ruby" } ] } [/block] After that you'll have the access token in the response: [block:code] { "codes": [ { "code": "access_token = JSON.parse(response)[\"access_token\"]\n# => 'c4739...'", "language": "ruby" } ] } [/block] And then, you can request access to protected resources. Unlike the previous version of the API, you no longer need to provide an Accept header. Instead, the version is passed in the URL path. The Authorization header with a Bearer token is still required, and should use the `access_token` from above: [block:code] { "codes": [ { "code": "# e.g.\nRestClient.post 'https://api.skillsengine.com/v2/competencies/analyze',\n { \n 'Authorization' => \"Bearer #{access_token}\",\n 'Content-Type' => \"application/json\"\n }", "language": "ruby" } ] } [/block] [block:callout] { "type": "warning", "body": "Ensure you are providing a **Content-Type** header with the value **application/json**. While many REST code libraries append this header automatically, if you are operating at a lower-level, or using a library that doesn't, you will need to specify this header yourself, otherwise you may get an empty result response." } [/block]
{"_id":"5b3a7fb938c5f700033508ad","category":"5b3a7fb938c5f7000335089e","project":"55e767022942b837005467a2","parentDoc":null,"user":"55e765965d36b32b00256428","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-15T22:12:05.638Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The SkillsEngine API is a JSON-based API service. As a result, it requires that you include a proper **Content-Type** header in every request, specifying **application/json**. Failure to do this will often result in an empty response.\"\n}\n[/block]","excerpt":"","slug":"content-type","type":"basic","title":"Content-Type","__v":0,"childrenPages":[]}

Content-Type


[block:callout] { "type": "warning", "body": "The SkillsEngine API is a JSON-based API service. As a result, it requires that you include a proper **Content-Type** header in every request, specifying **application/json**. Failure to do this will often result in an empty response." } [/block]
[block:callout] { "type": "warning", "body": "The SkillsEngine API is a JSON-based API service. As a result, it requires that you include a proper **Content-Type** header in every request, specifying **application/json**. Failure to do this will often result in an empty response." } [/block]
{"_id":"5b3a7fb938c5f700033508ae","category":"5b3a7fb938c5f7000335089e","parentDoc":null,"project":"55e767022942b837005467a2","user":"55e765965d36b32b00256428","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T17:16:40.165Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"The SkillsEngine API can produce fairly large and complex JSON results. In order to help keep everyone's bandwidth costs down and improve overall performance of apps interacting with the API, we've implemented GZIP-compressed output support.\n\nRequesting GZIP-compressed output is optional, but highly recommended, especially for apps expecting to do lots of API requests and apps that want to minimize the effects of network latency on those requests.\n\nTo receive GZIP-compressed output, simply include the standard *Accept-Encoding* header in your requests:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Accept-Encoding: gzip,deflate\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nThe API will then return all results in GZIP-compressed format. Before you can parse it with a JSON library, you'll need to decompress it. Nearly all major programming languages include libraries that should handle decompressing GZIP easily.\n\n### Example: Decompressing GZIP in Ruby\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'zlib'\\nstr_json = Zlib::GzipReader.new(response.body, encoding: 'ASCII-8BIT').read\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"compression","type":"basic","title":"Compression","__v":0,"childrenPages":[]}

Compression


The SkillsEngine API can produce fairly large and complex JSON results. In order to help keep everyone's bandwidth costs down and improve overall performance of apps interacting with the API, we've implemented GZIP-compressed output support. Requesting GZIP-compressed output is optional, but highly recommended, especially for apps expecting to do lots of API requests and apps that want to minimize the effects of network latency on those requests. To receive GZIP-compressed output, simply include the standard *Accept-Encoding* header in your requests: [block:code] { "codes": [ { "code": "Accept-Encoding: gzip,deflate", "language": "ruby" } ] } [/block] The API will then return all results in GZIP-compressed format. Before you can parse it with a JSON library, you'll need to decompress it. Nearly all major programming languages include libraries that should handle decompressing GZIP easily. ### Example: Decompressing GZIP in Ruby [block:code] { "codes": [ { "code": "require 'zlib'\nstr_json = Zlib::GzipReader.new(response.body, encoding: 'ASCII-8BIT').read", "language": "ruby" } ] } [/block]
The SkillsEngine API can produce fairly large and complex JSON results. In order to help keep everyone's bandwidth costs down and improve overall performance of apps interacting with the API, we've implemented GZIP-compressed output support. Requesting GZIP-compressed output is optional, but highly recommended, especially for apps expecting to do lots of API requests and apps that want to minimize the effects of network latency on those requests. To receive GZIP-compressed output, simply include the standard *Accept-Encoding* header in your requests: [block:code] { "codes": [ { "code": "Accept-Encoding: gzip,deflate", "language": "ruby" } ] } [/block] The API will then return all results in GZIP-compressed format. Before you can parse it with a JSON library, you'll need to decompress it. Nearly all major programming languages include libraries that should handle decompressing GZIP easily. ### Example: Decompressing GZIP in Ruby [block:code] { "codes": [ { "code": "require 'zlib'\nstr_json = Zlib::GzipReader.new(response.body, encoding: 'ASCII-8BIT').read", "language": "ruby" } ] } [/block]
{"_id":"5b3a7fb938c5f700033508a9","category":"5b3a7fb938c5f7000335089f","user":"55e765965d36b32b00256428","parentDoc":null,"project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T16:31:14.273Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"name":"","code":"response = RestClient.post 'https://api.skillsengine.com/api/token', {\n  grant_type: 'client_credentials',\n  client_id: client_id,\n  client_secret: client_secret\n}","language":"ruby"}]},"method":"post","results":{"codes":[{"status":200,"language":"json","code":"{\"access_token\":\"2aa1c12f3a6c17bf832d57c7ea6244071777dd64d6a489a1fe0654dfabe7a44a\",\"token_type\":\"bearer\",\"expires_in\":3600,\"created_at\":1441141199}","name":""},{"status":401,"language":"json","code":"{\"message\":\"Unauthorized, expired, or incorrect token request syntax\"}","name":""}]},"settings":"","auth":"required","params":[{"_id":"55e8771f34516037002e9370","ref":"","in":"body","required":true,"desc":"","default":"client_credentials","type":"string","name":"grant_type"},{"_id":"55e8771f34516037002e936f","ref":"","in":"body","required":true,"desc":"your assigned Client ID","default":"","type":"string","name":"ciient_id"},{"_id":"55e8771f34516037002e936e","ref":"","in":"body","required":true,"desc":"your assigned Client Secret","default":"","type":"string","name":"client_secret"}],"url":"/api/token"},"isReference":false,"order":4,"body":"","excerpt":"Provides a standard token-retrieval endpoint. A valid access token is required for all subsequent requests of the API's endpoints.","slug":"oauthtoken","type":"post","title":"/api/token","__v":0,"childrenPages":[]}

post/api/token

Provides a standard token-retrieval endpoint. A valid access token is required for all subsequent requests of the API's endpoints.

Body Params

grant_type:
required
stringclient_credentials
ciient_id:
required
string
your assigned Client ID
client_secret:
required
string
your assigned Client Secret

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5b3a7fb938c5f700033508aa","category":"5b3a7fb938c5f7000335089f","user":"55e765965d36b32b00256428","parentDoc":null,"project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T16:41:51.575Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"access_token = \"2aa1c12f3a6c17bf832d57c7ea6244071777dd64d6a489a1fe0654dfabe7a44a\"\nRestClient.get 'https://api.skillsengine.com/api/test',\n  { 'Authorization' => \"Bearer #{access_token}\" }","language":"ruby","name":""}]},"method":"get","results":{"codes":[{"name":"","code":"{\"message\":\"Token is authorized\"}","language":"json","status":200},{"name":"","code":"{\"message\":\"Unauthorized, expired, or incorrect token request syntax\"}","language":"json","status":401}]},"settings":"","auth":"required","params":[],"url":"/api/test"},"isReference":false,"order":5,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Authorization Header Required\",\n  \"body\": \"Like all endpoints (except the oauth/token endpoint), this endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\"\n}\n[/block]","excerpt":"Provides a simple endpoint for testing if your code and access token are valid for making requests of any of the API's other endpoints. This test endpoint does not consume a request for paying customers.","slug":"oauthtest","type":"get","title":"/api/test","__v":0,"childrenPages":[]}

get/api/test

Provides a simple endpoint for testing if your code and access token are valid for making requests of any of the API's other endpoints. This test endpoint does not consume a request for paying customers.

[block:callout] { "type": "warning", "title": "Authorization Header Required", "body": "Like all endpoints (except the oauth/token endpoint), this endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "title": "Authorization Header Required", "body": "Like all endpoints (except the oauth/token endpoint), this endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`." } [/block]
{"_id":"5c1bdbc48116e20667d2b8e6","project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","category":"5b3a7fb938c5f7000335089f","user":"55e765965d36b32b00256428","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-12-20T18:13:24.690Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"http","code":"GET /v2/skills/freshness"}]},"results":{"codes":[{"name":"","code":"{\"result\":{\"freshness_tag\":\"2a12aba8dcabc23f250c78dff46b5661\"}}","language":"json","status":200}]},"settings":"","auth":"required","params":[],"url":"/v2/skills/freshness","method":"get"},"isReference":false,"order":999,"body":"","excerpt":"Provides a simple endpoint for retrieving a \"freshness tag.\" Similar to HTTP Etags, you should request this tag periodically and store it in your app's datastore. This can be used to determine if any skills data has been updated on the SkillsEngine side since the last time you checked. If it hasn't, and you know that YOUR request data has not changed, then there's no need to make that same request, potentially saving you (and us!) many computationally-expensive requests that would just return the same data as last time.","slug":"v2skillsfreshness","type":"get","title":"/v2/skills/freshness","__v":0,"childrenPages":[]}

get/v2/skills/freshness

Provides a simple endpoint for retrieving a "freshness tag." Similar to HTTP Etags, you should request this tag periodically and store it in your app's datastore. This can be used to determine if any skills data has been updated on the SkillsEngine side since the last time you checked. If it hasn't, and you know that YOUR request data has not changed, then there's no need to make that same request, potentially saving you (and us!) many computationally-expensive requests that would just return the same data as last time.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"_id":"5b3a7fb938c5f700033508a6","category":"5b3a7fb938c5f700033508a0","parentDoc":null,"user":"55e765965d36b32b00256428","project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-21T16:35:10.915Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{\n  \"result\": {\n    \"competencies_analysis\": {\n      \"metadata\": {},\n      \"occupations\": [],\n      \"general_work_activities\": [],\n      \"intermediate_work_activities\": [],\n      \"detailed_work_activities\": [],\n      \"workplace_essentials\": [],\n      \"knowledges\": [],\n      \"knowledge_subdomains\": [],\n      \"skills\": [],      \n      \"abilities\": [],     \n      \"tools\": [],      \n    }\n  }\n}\n// see Analysis Elements for details","language":"json"}]},"settings":"","examples":{"codes":[{"language":"json","code":"POST /v2/competencies/analyze/flatten\n\n{\"text\":\"Provide substance abuse education and counseling for at-risk individuals.\",\"bias\":0.4}"}]},"method":"post","auth":"required","params":[{"_id":"56c4aa5b116c0d21000bcf3a","ref":"","in":"body","required":true,"desc":"unstructured text to analyze","default":"","type":"string","name":"text"},{"_id":"56c4aa5b116c0d21000bcf39","ref":"","in":"body","required":false,"desc":"decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results","default":"1.0","type":"string","name":"bias"},{"_id":"576972bc1f52a00e006a9665","ref":"","in":"body","required":false,"desc":"comma-separated list of element types to exclude from the analysis (see Excluding Elements)","default":"","type":"string","name":"exclude"}],"url":"/v2/competencies/analyze/flatten"},"isReference":false,"order":6,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Why \\\"Flattened\\\"?\"\n}\n[/block]\nWhile we believe the original hierarchical view of work activities holds tremendous value in showing how more granular activities relate to parent, higher-level groupings of activities, it became clear to us in talking with consumers of the API that there was often a greater desire to receive a simplified flat list of each type of work activity with corresponding scoring that shows how relevant a single work activity is to _all_ of its siblings, regardless of parentage.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Analysis Elements\"\n}\n[/block]\nSee the original, hierarchical Profiler for detailed information on the other available elements...\n\n#### Flattened Work Activities\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"      \\\"general_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Training and Teaching Others\\\",\\n          \\\"guid\\\": \\\"073cc097-39c5-4384-b410-2195e609634e\\\",\\n          \\\"score\\\": 45.52\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Provide Consultation and Advice to Others\\\",\\n          \\\"guid\\\": \\\"abe6cddd-0679-4491-ad7a-a672d72ceffb\\\",\\n          \\\"score\\\": 43.5\\n        },\\n        ...\\n      ],\\n      \\\"intermediate_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Counsel others about personal matters\\\",\\n          \\\"guid\\\": \\\"4b5db412-c1b8-47e4-9606-03244fdd7880\\\",\\n          \\\"score\\\": 33.82\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Evaluate patient or client condition or treatment options\\\",\\n          \\\"guid\\\": \\\"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\\\",\\n          \\\"score\\\": 28.82\\n        },\\n        ...\\n      ],\\n      \\\"detailed_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Assist clients with understanding personal problems\\\",\\n          \\\"guid\\\": \\\"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\\\",\\n          \\\"score\\\": 16.47\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Counsel clients or patients regarding personal issues or problems\\\",\\n          \\\"guid\\\": \\\"663e4b83-9fdb-4170-9888-e00c0731bd59\\\",\\n          \\\"score\\\": 15.61\\n        },\\n        ...\\n      ]\\n\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile in a flattened structure with relevancy scores. If you'd rather have work activities arranged in a hierarchical tree, see the /v2/competencies/analyze endpoint.","slug":"v2competenciesanalyzeflatten","type":"post","title":"/v2/competencies/analyze/flatten","__v":1,"childrenPages":[]}

post/v2/competencies/analyze/flatten

This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile in a flattened structure with relevancy scores. If you'd rather have work activities arranged in a hierarchical tree, see the /v2/competencies/analyze endpoint.

Body Params

text:
required
string
unstructured text to analyze
bias:
string1.0
decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results
exclude:
string
comma-separated list of element types to exclude from the analysis (see Excluding Elements)
[block:api-header] { "type": "basic", "title": "Why \"Flattened\"?" } [/block] While we believe the original hierarchical view of work activities holds tremendous value in showing how more granular activities relate to parent, higher-level groupings of activities, it became clear to us in talking with consumers of the API that there was often a greater desire to receive a simplified flat list of each type of work activity with corresponding scoring that shows how relevant a single work activity is to _all_ of its siblings, regardless of parentage. [block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] See the original, hierarchical Profiler for detailed information on the other available elements... #### Flattened Work Activities [block:code] { "codes": [ { "code": " \"general_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Training and Teaching Others\",\n \"guid\": \"073cc097-39c5-4384-b410-2195e609634e\",\n \"score\": 45.52\n },\n {\n \"version\": 2,\n \"title\": \"Provide Consultation and Advice to Others\",\n \"guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n \"score\": 43.5\n },\n ...\n ],\n \"intermediate_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Counsel others about personal matters\",\n \"guid\": \"4b5db412-c1b8-47e4-9606-03244fdd7880\",\n \"score\": 33.82\n },\n {\n \"version\": 2,\n \"title\": \"Evaluate patient or client condition or treatment options\",\n \"guid\": \"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\",\n \"score\": 28.82\n },\n ...\n ],\n \"detailed_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Assist clients with understanding personal problems\",\n \"guid\": \"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\",\n \"score\": 16.47\n },\n {\n \"version\": 2,\n \"title\": \"Counsel clients or patients regarding personal issues or problems\",\n \"guid\": \"663e4b83-9fdb-4170-9888-e00c0731bd59\",\n \"score\": 15.61\n },\n ...\n ]\n\n", "language": "json" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Why \"Flattened\"?" } [/block] While we believe the original hierarchical view of work activities holds tremendous value in showing how more granular activities relate to parent, higher-level groupings of activities, it became clear to us in talking with consumers of the API that there was often a greater desire to receive a simplified flat list of each type of work activity with corresponding scoring that shows how relevant a single work activity is to _all_ of its siblings, regardless of parentage. [block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] See the original, hierarchical Profiler for detailed information on the other available elements... #### Flattened Work Activities [block:code] { "codes": [ { "code": " \"general_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Training and Teaching Others\",\n \"guid\": \"073cc097-39c5-4384-b410-2195e609634e\",\n \"score\": 45.52\n },\n {\n \"version\": 2,\n \"title\": \"Provide Consultation and Advice to Others\",\n \"guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n \"score\": 43.5\n },\n ...\n ],\n \"intermediate_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Counsel others about personal matters\",\n \"guid\": \"4b5db412-c1b8-47e4-9606-03244fdd7880\",\n \"score\": 33.82\n },\n {\n \"version\": 2,\n \"title\": \"Evaluate patient or client condition or treatment options\",\n \"guid\": \"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\",\n \"score\": 28.82\n },\n ...\n ],\n \"detailed_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Assist clients with understanding personal problems\",\n \"guid\": \"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\",\n \"score\": 16.47\n },\n {\n \"version\": 2,\n \"title\": \"Counsel clients or patients regarding personal issues or problems\",\n \"guid\": \"663e4b83-9fdb-4170-9888-e00c0731bd59\",\n \"score\": 15.61\n },\n ...\n ]\n\n", "language": "json" } ] } [/block]
{"_id":"5b3a7fb938c5f700033508a7","category":"5b3a7fb938c5f700033508a0","project":"55e767022942b837005467a2","user":"55e765965d36b32b00256428","parentDoc":null,"version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-17T17:26:00.413Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"POST /v2/competencies/analyze\n\n{\"text\":\"i am a welder and used welding equipment and acetylene torches\",\"bias\":0.4}","language":"json"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"result\": {\n    \"competencies_analysis\": {\n      \"metadata\": {},\n      \"occupations\": [],\n      \"general_work_activities\": [],\n      \"workplace_essentials\": [],\n      \"knowledges\": [],\n      \"knowledge_subdomains\": [],\n      \"skills\": [],      \n      \"abilities\": [],     \n      \"tools\": [],      \n    }\n  }\n}\n// see Analysis Elements for details","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"56c4aa5b116c0d21000bcf3a","ref":"","in":"body","required":true,"desc":"unstructured text to analyze","default":"","type":"string","name":"text"},{"_id":"56c4aa5b116c0d21000bcf39","ref":"","in":"body","required":false,"desc":"decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results","default":"1.0","type":"string","name":"bias"},{"_id":"576972b2e93bfd19002880fa","ref":"","in":"body","required":false,"desc":"comma-separated list of element types to exclude from the analysis (see Excluding Elements)","default":"","type":"string","name":"exclude"}],"url":"/v2/competencies/analyze"},"isReference":false,"order":7,"body":"### Explanation\n\nProfiler's response JSON includes a variety of arrays, each containing information Profiler has derived from the provided text. The analysis includes:\n\n* Occupations (ranked and ordered)\n* General Work Activities (as a hierarchy, ranked and ordered)\n    * Intermediate Work Activities\n        * Detailed Work Activities\n* Workplace Basics (ranked and ordered)\n* Knowledges (ranked and ordered)\n    * Knowledge Subdomains (ranked and ordered)\n* Skills (ranked and ordered)\n* Abilities (ranked and ordered)\n* Tools and Technologies (ranked and ordered)\n\nNote that the work activities are presented as a hierarchy of nested arrays, each containing many hashes. This is because General, Intermediate, and Detailed work activities are associated in a hierarchical structure and the analysis is intended to preserve those valuable relationships. Developers can, of course, extract information from this structure and aggregate, roll-up, re-sort, etc. as they see fit for use in their own application.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Analysis Elements\"\n}\n[/block]\nProfiler's response JSON includes several elements:\n\n#### Metadata\n\nNotes some basic metadata about this specific analysis...\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"metadata\\\": {\\n  \\\"text_size\\\": 12345,\\n  \\\"state_code\\\": \\\"TX\\\",\\n  \\\"parse_time\\\": 0.243965\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Occupations\n\nO*NET Standard Occupational Classification codes, titles, and relevancy scores.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"occupations\\\": [\\n  {\\n    \\\"code\\\": \\\"51-4121\\\",\\n    \\\"title\\\": \\\"Welders, Cutters, Solderers, and Brazers\\\",\\n    \\\"score\\\": 63.12\\n  },\\n  {\\n    \\\"code\\\": \\\"51-4122\\\",\\n    \\\"title\\\": \\\"Welding, Soldering, and Brazing Machine Setters, Operators, and Tenders\\\",\\n    \\\"score\\\": 36.88\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Work Activities Tree\n\nA work activity describes how major units of time are organized on the job. Every statement theoretically has distinctive starting and ending points. Each is observable and produces results susceptible to being measured. Each array includes a General high-level statement, more specific Intermediate statement and, finally, the Detailed Work Activity. Each Detailed Work Activity includes an action verb (required), object (required), and contextual modifiers.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"general_work_activities\\\": [\\n  {\\n    \\\"score\\\": 36.35,\\n    \\\"title\\\": \\\"Handling and Moving Objects\\\",\\n    \\\"intermediate_work_activities\\\": [\\n      {\\n        \\\"score\\\": 49.57,\\n        \\\"title\\\": \\\"Assemble equipment or components.\\\",\\n        \\\"detailed_work_activities\\\": [\\n          {\\n            \\\"score\\\": 43.64,\\n            \\\"title\\\": \\\"Construct patterns or templates for welding projects\\\"\\n          },\\n          {\\n            \\\"score\\\": 37.22,\\n            \\\"title\\\": \\\"Adjust equipment or instruments to specification\\\"\\n          },\\n          ...\\n        ]\\n      },\\n      ...\\n    ]\\n  },\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Workplace Essentials\n\nWorkplace Essentials (aka “soft skills”) are specific behaviors and characteristics that demonstrate general strengths in areas such as teamwork, attention to detail, communication and customer service. SkillsEngine uses 30 statements to describe the most important social and behavioral characteristics.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"workplace_essentials\\\": [\\n  [ \\\"Attention to Detail\\\", 93.74 ],\\n  [ \\\"Work Ethic\\\", 28.68 ],\\n  [ \\\"Information Gathering\\\", 10.06 ],\\n  [ \\\"Following Directions\\\", 8.29 ],\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Knowledges, Knowledge Subdomains, Skills, and Abilities\n\nKnowledges, Skills and Abilities can be assigned both to people and to jobs making them valuable indicators in the job matching process. Knowledges are principles, bodies of content and facts generally applied within academic domains. Knowledge Subdomains are a more granular breakout of Knowledges into topics of greater detail within the context of the parent Knowledge. A Skill is a developed capacity like time management or information gathering that facilitates performance of various tasks and activities across occupations or the rapid acquisition of relevant knowledge. An Ability is an attribute of an individual that can influence performance on the job.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"knowledges\\\": [\\n  [ \\\"Mechanical\\\", 92.01 ],\\n  [ \\\"Production and Processing\\\", 32.67 ],\\n  [ \\\"Building and Construction\\\", 15.87 ],\\n  ...\\n]\\n\\\"skills\\\": [\\n  [ \\\"Operation and Control\\\", 63.38 ],\\n  [ \\\"Equipment Selection\\\", 44.57 ],\\n  [ \\\"Reading Comprehension\\\", 39.63 ],\\n  ...\\n]\\n\\\"abilities\\\": [\\n  [ \\\"Manual Dexterity\\\", 93.06 ],\\n  [ \\\"Deductive Reasoning\\\", 18.82 ],\\n  [ \\\"Information Ordering\\\", 17.77 ],\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Tools and Technologies (experimental)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Tools and Technologies output is currently considered an **experimental** feature and is only intended for use in early stage development and prototyping.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"tools_techs\\\": [\\n  {\\n    \\\"score\\\": 89.08,\\n    \\\"type\\\": \\\"Tools\\\",\\n    \\\"title\\\": \\\"Speed sensors\\\",\\n    \\\"example\\\": \\\"Wire feed rate measurement instruments\\\"\\n  },\\n  {\\n    \\\"score\\\": 59.39,\\n    \\\"type\\\": \\\"Tools\\\",\\n    \\\"title\\\": \\\"Desktop computers\\\",\\n    \\\"example\\\": \\\"Desktop computers\\\"\\n  },\\n  {\\n    \\\"score\\\": 29.69,\\n    \\\"type\\\": \\\"Technology\\\",\\n    \\\"title\\\": \\\"Analytical or scientific software\\\",\\n    \\\"example\\\": \\\"Scientific Software Group Filter Drain FD\\\"\\n  },\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Relevancy Scores\n\nOur scoring mechanisms are based on a number of factors, including result frequencies and proprietary weights. The intent is to provide the consumer of the data with a simple way to sort and compare general relevance of a particular element with other elements of the same type. Within a group of elements of the same type, higher scores indicate greater relevance of that element to the overall analysis than lower scores.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Scores are relative only to elements of the same type (General Work Activity scores have no relevance to Detailed Work Activity scores, for example)\"\n}\n[/block]","excerpt":"This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile, with work activities arranged in a hierarchical tree where relevancy scores are contextualized to branches of the tree.","slug":"v2competenciesanalyze","type":"post","title":"/v2/competencies/analyze","__v":2,"childrenPages":[]}

post/v2/competencies/analyze

This endpoint parses unstructured text, evaluates that text, and produces a detailed competencies profile, with work activities arranged in a hierarchical tree where relevancy scores are contextualized to branches of the tree.

Body Params

text:
required
string
unstructured text to analyze
bias:
string1.0
decimal between 0.1 and 1.0; biases the analysis algorithms towards more granular or more general results
exclude:
string
comma-separated list of element types to exclude from the analysis (see Excluding Elements)
### Explanation Profiler's response JSON includes a variety of arrays, each containing information Profiler has derived from the provided text. The analysis includes: * Occupations (ranked and ordered) * General Work Activities (as a hierarchy, ranked and ordered) * Intermediate Work Activities * Detailed Work Activities * Workplace Basics (ranked and ordered) * Knowledges (ranked and ordered) * Knowledge Subdomains (ranked and ordered) * Skills (ranked and ordered) * Abilities (ranked and ordered) * Tools and Technologies (ranked and ordered) Note that the work activities are presented as a hierarchy of nested arrays, each containing many hashes. This is because General, Intermediate, and Detailed work activities are associated in a hierarchical structure and the analysis is intended to preserve those valuable relationships. Developers can, of course, extract information from this structure and aggregate, roll-up, re-sort, etc. as they see fit for use in their own application. [block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] Profiler's response JSON includes several elements: #### Metadata Notes some basic metadata about this specific analysis... [block:code] { "codes": [ { "code": "\"metadata\": {\n \"text_size\": 12345,\n \"state_code\": \"TX\",\n \"parse_time\": 0.243965\n}", "language": "json" } ] } [/block] #### Occupations O*NET Standard Occupational Classification codes, titles, and relevancy scores. [block:code] { "codes": [ { "code": "\"occupations\": [\n {\n \"code\": \"51-4121\",\n \"title\": \"Welders, Cutters, Solderers, and Brazers\",\n \"score\": 63.12\n },\n {\n \"code\": \"51-4122\",\n \"title\": \"Welding, Soldering, and Brazing Machine Setters, Operators, and Tenders\",\n \"score\": 36.88\n }\n]", "language": "json" } ] } [/block] #### Work Activities Tree A work activity describes how major units of time are organized on the job. Every statement theoretically has distinctive starting and ending points. Each is observable and produces results susceptible to being measured. Each array includes a General high-level statement, more specific Intermediate statement and, finally, the Detailed Work Activity. Each Detailed Work Activity includes an action verb (required), object (required), and contextual modifiers. [block:code] { "codes": [ { "code": "\"general_work_activities\": [\n {\n \"score\": 36.35,\n \"title\": \"Handling and Moving Objects\",\n \"intermediate_work_activities\": [\n {\n \"score\": 49.57,\n \"title\": \"Assemble equipment or components.\",\n \"detailed_work_activities\": [\n {\n \"score\": 43.64,\n \"title\": \"Construct patterns or templates for welding projects\"\n },\n {\n \"score\": 37.22,\n \"title\": \"Adjust equipment or instruments to specification\"\n },\n ...\n ]\n },\n ...\n ]\n },\n ...\n]", "language": "json" } ] } [/block] #### Workplace Essentials Workplace Essentials (aka “soft skills”) are specific behaviors and characteristics that demonstrate general strengths in areas such as teamwork, attention to detail, communication and customer service. SkillsEngine uses 30 statements to describe the most important social and behavioral characteristics. [block:code] { "codes": [ { "code": "\"workplace_essentials\": [\n [ \"Attention to Detail\", 93.74 ],\n [ \"Work Ethic\", 28.68 ],\n [ \"Information Gathering\", 10.06 ],\n [ \"Following Directions\", 8.29 ],\n ...\n]", "language": "json" } ] } [/block] #### Knowledges, Knowledge Subdomains, Skills, and Abilities Knowledges, Skills and Abilities can be assigned both to people and to jobs making them valuable indicators in the job matching process. Knowledges are principles, bodies of content and facts generally applied within academic domains. Knowledge Subdomains are a more granular breakout of Knowledges into topics of greater detail within the context of the parent Knowledge. A Skill is a developed capacity like time management or information gathering that facilitates performance of various tasks and activities across occupations or the rapid acquisition of relevant knowledge. An Ability is an attribute of an individual that can influence performance on the job. [block:code] { "codes": [ { "code": "\"knowledges\": [\n [ \"Mechanical\", 92.01 ],\n [ \"Production and Processing\", 32.67 ],\n [ \"Building and Construction\", 15.87 ],\n ...\n]\n\"skills\": [\n [ \"Operation and Control\", 63.38 ],\n [ \"Equipment Selection\", 44.57 ],\n [ \"Reading Comprehension\", 39.63 ],\n ...\n]\n\"abilities\": [\n [ \"Manual Dexterity\", 93.06 ],\n [ \"Deductive Reasoning\", 18.82 ],\n [ \"Information Ordering\", 17.77 ],\n ...\n]", "language": "json" } ] } [/block] #### Tools and Technologies (experimental) [block:callout] { "type": "warning", "body": "Tools and Technologies output is currently considered an **experimental** feature and is only intended for use in early stage development and prototyping." } [/block] [block:code] { "codes": [ { "code": "\"tools_techs\": [\n {\n \"score\": 89.08,\n \"type\": \"Tools\",\n \"title\": \"Speed sensors\",\n \"example\": \"Wire feed rate measurement instruments\"\n },\n {\n \"score\": 59.39,\n \"type\": \"Tools\",\n \"title\": \"Desktop computers\",\n \"example\": \"Desktop computers\"\n },\n {\n \"score\": 29.69,\n \"type\": \"Technology\",\n \"title\": \"Analytical or scientific software\",\n \"example\": \"Scientific Software Group Filter Drain FD\"\n },\n ...\n]", "language": "json" } ] } [/block] #### Relevancy Scores Our scoring mechanisms are based on a number of factors, including result frequencies and proprietary weights. The intent is to provide the consumer of the data with a simple way to sort and compare general relevance of a particular element with other elements of the same type. Within a group of elements of the same type, higher scores indicate greater relevance of that element to the overall analysis than lower scores. [block:callout] { "type": "info", "body": "Scores are relative only to elements of the same type (General Work Activity scores have no relevance to Detailed Work Activity scores, for example)" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



### Explanation Profiler's response JSON includes a variety of arrays, each containing information Profiler has derived from the provided text. The analysis includes: * Occupations (ranked and ordered) * General Work Activities (as a hierarchy, ranked and ordered) * Intermediate Work Activities * Detailed Work Activities * Workplace Basics (ranked and ordered) * Knowledges (ranked and ordered) * Knowledge Subdomains (ranked and ordered) * Skills (ranked and ordered) * Abilities (ranked and ordered) * Tools and Technologies (ranked and ordered) Note that the work activities are presented as a hierarchy of nested arrays, each containing many hashes. This is because General, Intermediate, and Detailed work activities are associated in a hierarchical structure and the analysis is intended to preserve those valuable relationships. Developers can, of course, extract information from this structure and aggregate, roll-up, re-sort, etc. as they see fit for use in their own application. [block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] Profiler's response JSON includes several elements: #### Metadata Notes some basic metadata about this specific analysis... [block:code] { "codes": [ { "code": "\"metadata\": {\n \"text_size\": 12345,\n \"state_code\": \"TX\",\n \"parse_time\": 0.243965\n}", "language": "json" } ] } [/block] #### Occupations O*NET Standard Occupational Classification codes, titles, and relevancy scores. [block:code] { "codes": [ { "code": "\"occupations\": [\n {\n \"code\": \"51-4121\",\n \"title\": \"Welders, Cutters, Solderers, and Brazers\",\n \"score\": 63.12\n },\n {\n \"code\": \"51-4122\",\n \"title\": \"Welding, Soldering, and Brazing Machine Setters, Operators, and Tenders\",\n \"score\": 36.88\n }\n]", "language": "json" } ] } [/block] #### Work Activities Tree A work activity describes how major units of time are organized on the job. Every statement theoretically has distinctive starting and ending points. Each is observable and produces results susceptible to being measured. Each array includes a General high-level statement, more specific Intermediate statement and, finally, the Detailed Work Activity. Each Detailed Work Activity includes an action verb (required), object (required), and contextual modifiers. [block:code] { "codes": [ { "code": "\"general_work_activities\": [\n {\n \"score\": 36.35,\n \"title\": \"Handling and Moving Objects\",\n \"intermediate_work_activities\": [\n {\n \"score\": 49.57,\n \"title\": \"Assemble equipment or components.\",\n \"detailed_work_activities\": [\n {\n \"score\": 43.64,\n \"title\": \"Construct patterns or templates for welding projects\"\n },\n {\n \"score\": 37.22,\n \"title\": \"Adjust equipment or instruments to specification\"\n },\n ...\n ]\n },\n ...\n ]\n },\n ...\n]", "language": "json" } ] } [/block] #### Workplace Essentials Workplace Essentials (aka “soft skills”) are specific behaviors and characteristics that demonstrate general strengths in areas such as teamwork, attention to detail, communication and customer service. SkillsEngine uses 30 statements to describe the most important social and behavioral characteristics. [block:code] { "codes": [ { "code": "\"workplace_essentials\": [\n [ \"Attention to Detail\", 93.74 ],\n [ \"Work Ethic\", 28.68 ],\n [ \"Information Gathering\", 10.06 ],\n [ \"Following Directions\", 8.29 ],\n ...\n]", "language": "json" } ] } [/block] #### Knowledges, Knowledge Subdomains, Skills, and Abilities Knowledges, Skills and Abilities can be assigned both to people and to jobs making them valuable indicators in the job matching process. Knowledges are principles, bodies of content and facts generally applied within academic domains. Knowledge Subdomains are a more granular breakout of Knowledges into topics of greater detail within the context of the parent Knowledge. A Skill is a developed capacity like time management or information gathering that facilitates performance of various tasks and activities across occupations or the rapid acquisition of relevant knowledge. An Ability is an attribute of an individual that can influence performance on the job. [block:code] { "codes": [ { "code": "\"knowledges\": [\n [ \"Mechanical\", 92.01 ],\n [ \"Production and Processing\", 32.67 ],\n [ \"Building and Construction\", 15.87 ],\n ...\n]\n\"skills\": [\n [ \"Operation and Control\", 63.38 ],\n [ \"Equipment Selection\", 44.57 ],\n [ \"Reading Comprehension\", 39.63 ],\n ...\n]\n\"abilities\": [\n [ \"Manual Dexterity\", 93.06 ],\n [ \"Deductive Reasoning\", 18.82 ],\n [ \"Information Ordering\", 17.77 ],\n ...\n]", "language": "json" } ] } [/block] #### Tools and Technologies (experimental) [block:callout] { "type": "warning", "body": "Tools and Technologies output is currently considered an **experimental** feature and is only intended for use in early stage development and prototyping." } [/block] [block:code] { "codes": [ { "code": "\"tools_techs\": [\n {\n \"score\": 89.08,\n \"type\": \"Tools\",\n \"title\": \"Speed sensors\",\n \"example\": \"Wire feed rate measurement instruments\"\n },\n {\n \"score\": 59.39,\n \"type\": \"Tools\",\n \"title\": \"Desktop computers\",\n \"example\": \"Desktop computers\"\n },\n {\n \"score\": 29.69,\n \"type\": \"Technology\",\n \"title\": \"Analytical or scientific software\",\n \"example\": \"Scientific Software Group Filter Drain FD\"\n },\n ...\n]", "language": "json" } ] } [/block] #### Relevancy Scores Our scoring mechanisms are based on a number of factors, including result frequencies and proprietary weights. The intent is to provide the consumer of the data with a simple way to sort and compare general relevance of a particular element with other elements of the same type. Within a group of elements of the same type, higher scores indicate greater relevance of that element to the overall analysis than lower scores. [block:callout] { "type": "info", "body": "Scores are relative only to elements of the same type (General Work Activity scores have no relevance to Detailed Work Activity scores, for example)" } [/block]
{"_id":"5b3a7fb938c5f700033508a8","category":"5b3a7fb938c5f700033508a0","parentDoc":null,"user":"55e765965d36b32b00256428","project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-21T16:44:08.319Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"code":"{}","name":"","status":400,"language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"Profiler supports more precise shaping of API requests in order to specifically exclude any of the normally-returned skill elements. This allows consumers of the API to determine what they do and do not need, which consequently makes the response smaller and the processing of the request quicker.\n\nTo exclude elements from the response, simply **provide an `exclude` parameter with a comma-separated list of one or more element names** that should _not_ be in the response.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"metadata\\noccupations\\ngeneral_work_activities\\nintermediate_work_activities\\ndetailed_work_activities\\nworkplace_essentials\\nknowledges\\nknowledge_subdomains\\nskills\\nabilities\\ntools\",\n      \"language\": \"text\",\n      \"name\": \"Valid Element Names\"\n    }\n  ]\n}\n[/block]\nThis new functionality is optional. By default, both `/competencies/analyze` endpoints will return *all* data elements. To use the exclusion feature, simply provide an additional `exclude` parameter in the JSON body of your request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /v2/competencies/analyze\\n\\n{\\\"text\\\":\\\"i am a welder and used welding equipment and acetylene torches\\\",\\\"bias\\\":0.4, \\\"exclude\\\":\\\"occupations,detailed_work_activities,knowledges,abilities,tools\\\"}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Caveat\"\n}\n[/block]\nThe \"flat\" profile and \"hierarchical\" profile respond differently when asked to exclude one or more of the `work_activities` data elements. \n\nFor the flat profile, the response will simply exclude the specific work activities list(s) as specified in the request parameters. \n\nFor the hierarchical profile, the response will exclude the specific work activities specified _as well as_ any sets below those in the tree. For example, asking to exclude `intermediate_work_activities` will exclude those as well as all `detailed_work_activities`. Asking to exclude `general_work_activities` will effectively exclude all work activity types from the response.","excerpt":"","slug":"excluding-elements","type":"basic","title":"Excluding Elements","__v":0,"childrenPages":[]}

Excluding Elements


Profiler supports more precise shaping of API requests in order to specifically exclude any of the normally-returned skill elements. This allows consumers of the API to determine what they do and do not need, which consequently makes the response smaller and the processing of the request quicker. To exclude elements from the response, simply **provide an `exclude` parameter with a comma-separated list of one or more element names** that should _not_ be in the response. [block:code] { "codes": [ { "code": "metadata\noccupations\ngeneral_work_activities\nintermediate_work_activities\ndetailed_work_activities\nworkplace_essentials\nknowledges\nknowledge_subdomains\nskills\nabilities\ntools", "language": "text", "name": "Valid Element Names" } ] } [/block] This new functionality is optional. By default, both `/competencies/analyze` endpoints will return *all* data elements. To use the exclusion feature, simply provide an additional `exclude` parameter in the JSON body of your request: [block:code] { "codes": [ { "code": "POST /v2/competencies/analyze\n\n{\"text\":\"i am a welder and used welding equipment and acetylene torches\",\"bias\":0.4, \"exclude\":\"occupations,detailed_work_activities,knowledges,abilities,tools\"}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Caveat" } [/block] The "flat" profile and "hierarchical" profile respond differently when asked to exclude one or more of the `work_activities` data elements. For the flat profile, the response will simply exclude the specific work activities list(s) as specified in the request parameters. For the hierarchical profile, the response will exclude the specific work activities specified _as well as_ any sets below those in the tree. For example, asking to exclude `intermediate_work_activities` will exclude those as well as all `detailed_work_activities`. Asking to exclude `general_work_activities` will effectively exclude all work activity types from the response.
Profiler supports more precise shaping of API requests in order to specifically exclude any of the normally-returned skill elements. This allows consumers of the API to determine what they do and do not need, which consequently makes the response smaller and the processing of the request quicker. To exclude elements from the response, simply **provide an `exclude` parameter with a comma-separated list of one or more element names** that should _not_ be in the response. [block:code] { "codes": [ { "code": "metadata\noccupations\ngeneral_work_activities\nintermediate_work_activities\ndetailed_work_activities\nworkplace_essentials\nknowledges\nknowledge_subdomains\nskills\nabilities\ntools", "language": "text", "name": "Valid Element Names" } ] } [/block] This new functionality is optional. By default, both `/competencies/analyze` endpoints will return *all* data elements. To use the exclusion feature, simply provide an additional `exclude` parameter in the JSON body of your request: [block:code] { "codes": [ { "code": "POST /v2/competencies/analyze\n\n{\"text\":\"i am a welder and used welding equipment and acetylene torches\",\"bias\":0.4, \"exclude\":\"occupations,detailed_work_activities,knowledges,abilities,tools\"}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Caveat" } [/block] The "flat" profile and "hierarchical" profile respond differently when asked to exclude one or more of the `work_activities` data elements. For the flat profile, the response will simply exclude the specific work activities list(s) as specified in the request parameters. For the hierarchical profile, the response will exclude the specific work activities specified _as well as_ any sets below those in the tree. For example, asking to exclude `intermediate_work_activities` will exclude those as well as all `detailed_work_activities`. Asking to exclude `general_work_activities` will effectively exclude all work activity types from the response.
{"_id":"5b3a7fb938c5f700033508af","category":"5b3a7fb938c5f700033508a1","project":"55e767022942b837005467a2","user":"55e765965d36b32b00256428","parentDoc":null,"version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-12-16T19:24:34.607Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[{"language":"json","code":"POST /v2/competencies/analyze/military\n\n{\"moc\":\"2A554E\"}"}]},"method":"post","results":{"codes":[{"status":200,"name":"","code":"{\n  \"result\": {\n    \"competencies_analysis\": {\n      \"metadata\": {},\n      \"occupations\": [],\n      \"general_work_activities\": [],\n      \"intermediate_work_activities\": [],\n      \"detailed_work_activities\": [],\n      \"workplace_essentials\": [],\n      \"knowledges\": [],\n      \"knowledge_subdomains\": [],\n      \"skills\": [],      \n      \"abilities\": [],     \n      \"tools\": [],\n      \"mocs\": []\n    }\n  }\n}\n// see Analysis Elements for details","language":"json"}]},"auth":"required","params":[{"_id":"56c4aa5b116c0d21000bcf39","ref":"","in":"body","required":true,"desc":"known MOC in all-caps","default":"","type":"string","name":"moc"},{"_id":"585442c598629b0f004d6007","ref":"","in":"body","required":false,"desc":"helps disambiguate MOCs used by more than one service; must be `navy`, `army`, `coast guard`, `marine corps`, `air force`, or `special forces`","default":"","type":"string","name":"service_branch"},{"_id":"585442c598629b0f004d6006","ref":"","in":"body","required":false,"desc":"helps disambiguate different military roles held; must be one of `officer`, `warrant`, or `enlisted`","default":"","type":"string","name":"mpc"},{"_id":"585442c598629b0f004d6005","ref":"","in":"body","required":false,"desc":"comma-separated list of element types to exclude from the analysis (see Excluding Elements in the Profiler section)","default":"","type":"string","name":"exclude"},{"_id":"585442c598629b0f004d6004","ref":"","in":"body","required":false,"desc":"when the individual started their service; helps disambiguate in the case where a MOC was later recycled for a new use","default":"yyyy/mm/dd","type":"string","name":"start_date"},{"_id":"585442c598629b0f004d6003","ref":"","in":"body","required":false,"desc":"when the individual completed their service; helps disambiguate in the case where a MOC was later recycled for a new use","default":"yyyy/mm/dd","type":"string","name":"end_date"},{"_id":"5a9f043eef97780044db22dd","ref":"","in":"body","required":false,"desc":"leave blank, or one of `current_only`, `obsolete_only`, or `all`","default":"current_only","type":"string","name":"moc_status"}],"url":"/v2/competencies/analyze/military"},"isReference":false,"order":9,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Analysis Elements\"\n}\n[/block]\n#### Occupations\n\nIn the case of the Warrior endpoint, you may notice that the Occupations list does not include scores. This is intentional. Because of how Warrior does its inference, scores are not available for the occupations matched. In the case of multiple occupational matches, all occupations should be considered equal-weight suggestions.\n\n#### Flattened Work Activities\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"      \\\"general_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Training and Teaching Others\\\",\\n          \\\"guid\\\": \\\"073cc097-39c5-4384-b410-2195e609634e\\\",\\n          \\\"score\\\": 45.52\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Provide Consultation and Advice to Others\\\",\\n          \\\"guid\\\": \\\"abe6cddd-0679-4491-ad7a-a672d72ceffb\\\",\\n          \\\"score\\\": 43.5\\n        },\\n        ...\\n      ],\\n      \\\"intermediate_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Counsel others about personal matters\\\",\\n          \\\"guid\\\": \\\"4b5db412-c1b8-47e4-9606-03244fdd7880\\\",\\n          \\\"score\\\": 33.82\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Evaluate patient or client condition or treatment options\\\",\\n          \\\"guid\\\": \\\"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\\\",\\n          \\\"score\\\": 28.82\\n        },\\n        ...\\n      ],\\n      \\\"detailed_work_activities\\\": [\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Assist clients with understanding personal problems\\\",\\n          \\\"guid\\\": \\\"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\\\",\\n          \\\"score\\\": 16.47\\n        },\\n        {\\n          \\\"version\\\": 2,\\n          \\\"title\\\": \\\"Counsel clients or patients regarding personal issues or problems\\\",\\n          \\\"guid\\\": \\\"663e4b83-9fdb-4170-9888-e00c0731bd59\\\",\\n          \\\"score\\\": 15.61\\n        },\\n        ...\\n      ]\\n\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### MOCs\n\nWith the Warrior endpoint, we provide an additional array of the actual MOCs matched in our library, along with metadata about each. Because the same MOC might be used for different things by different service branches, or represent multiple MPCs within a single branch, this array may contain multiple elements. The intent is for this to provide downstream consumers with a means by which to prompt their users for more detail in order to focus the profile match (e.g. \"Which of the following Service Branches did you mean?\")\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"mocs\\\": [\\n\\t{\\n\\t\\t\\\"moc\\\": \\\"2A554E\\\",\\n\\t\\t\\\"mpc\\\": \\\"enlisted\\\",\\n\\t\\t\\\"service_branch\\\": \\\"air force\\\",\\n\\t\\t\\\"moc_title\\\": \\\"Refuel/Bomber Aircraft Maintenance Journeyman, B-1\\\"\\n  },\\n  ...\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Other Elements\n\nSee the [original, hierarchical Profiler](https://dev.skillsengine.com/docs/v2competenciesanalyze) for detailed information on the other available elements...","excerpt":"This endpoint evaluates a provided MOC (as well as some additional optional parameters) and produces a detailed competencies profile in a flattened structure that represents civilian skills and occupations that most closely relate to the military role identified by the MOC.","slug":"v2competenciesanalyzemilitary","type":"post","title":"/v2/competencies/analyze/military","__v":4,"childrenPages":[]}

post/v2/competencies/analyze/military

This endpoint evaluates a provided MOC (as well as some additional optional parameters) and produces a detailed competencies profile in a flattened structure that represents civilian skills and occupations that most closely relate to the military role identified by the MOC.

Body Params

moc:
required
string
known MOC in all-caps
service_branch:
string
helps disambiguate MOCs used by more than one service; must be `navy`, `army`, `coast guard`, `marine corps`, `air force`, or `special forces`
mpc:
string
helps disambiguate different military roles held; must be one of `officer`, `warrant`, or `enlisted`
exclude:
string
comma-separated list of element types to exclude from the analysis (see Excluding Elements in the Profiler section)
start_date:
stringyyyy/mm/dd
when the individual started their service; helps disambiguate in the case where a MOC was later recycled for a new use
end_date:
stringyyyy/mm/dd
when the individual completed their service; helps disambiguate in the case where a MOC was later recycled for a new use
moc_status:
stringcurrent_only
leave blank, or one of `current_only`, `obsolete_only`, or `all`
[block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] #### Occupations In the case of the Warrior endpoint, you may notice that the Occupations list does not include scores. This is intentional. Because of how Warrior does its inference, scores are not available for the occupations matched. In the case of multiple occupational matches, all occupations should be considered equal-weight suggestions. #### Flattened Work Activities [block:code] { "codes": [ { "code": " \"general_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Training and Teaching Others\",\n \"guid\": \"073cc097-39c5-4384-b410-2195e609634e\",\n \"score\": 45.52\n },\n {\n \"version\": 2,\n \"title\": \"Provide Consultation and Advice to Others\",\n \"guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n \"score\": 43.5\n },\n ...\n ],\n \"intermediate_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Counsel others about personal matters\",\n \"guid\": \"4b5db412-c1b8-47e4-9606-03244fdd7880\",\n \"score\": 33.82\n },\n {\n \"version\": 2,\n \"title\": \"Evaluate patient or client condition or treatment options\",\n \"guid\": \"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\",\n \"score\": 28.82\n },\n ...\n ],\n \"detailed_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Assist clients with understanding personal problems\",\n \"guid\": \"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\",\n \"score\": 16.47\n },\n {\n \"version\": 2,\n \"title\": \"Counsel clients or patients regarding personal issues or problems\",\n \"guid\": \"663e4b83-9fdb-4170-9888-e00c0731bd59\",\n \"score\": 15.61\n },\n ...\n ]\n\n", "language": "json" } ] } [/block] #### MOCs With the Warrior endpoint, we provide an additional array of the actual MOCs matched in our library, along with metadata about each. Because the same MOC might be used for different things by different service branches, or represent multiple MPCs within a single branch, this array may contain multiple elements. The intent is for this to provide downstream consumers with a means by which to prompt their users for more detail in order to focus the profile match (e.g. "Which of the following Service Branches did you mean?") [block:code] { "codes": [ { "code": "\"mocs\": [\n\t{\n\t\t\"moc\": \"2A554E\",\n\t\t\"mpc\": \"enlisted\",\n\t\t\"service_branch\": \"air force\",\n\t\t\"moc_title\": \"Refuel/Bomber Aircraft Maintenance Journeyman, B-1\"\n },\n ...\n]", "language": "json" } ] } [/block] #### Other Elements See the [original, hierarchical Profiler](https://dev.skillsengine.com/docs/v2competenciesanalyze) for detailed information on the other available elements...

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Analysis Elements" } [/block] #### Occupations In the case of the Warrior endpoint, you may notice that the Occupations list does not include scores. This is intentional. Because of how Warrior does its inference, scores are not available for the occupations matched. In the case of multiple occupational matches, all occupations should be considered equal-weight suggestions. #### Flattened Work Activities [block:code] { "codes": [ { "code": " \"general_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Training and Teaching Others\",\n \"guid\": \"073cc097-39c5-4384-b410-2195e609634e\",\n \"score\": 45.52\n },\n {\n \"version\": 2,\n \"title\": \"Provide Consultation and Advice to Others\",\n \"guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n \"score\": 43.5\n },\n ...\n ],\n \"intermediate_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Counsel others about personal matters\",\n \"guid\": \"4b5db412-c1b8-47e4-9606-03244fdd7880\",\n \"score\": 33.82\n },\n {\n \"version\": 2,\n \"title\": \"Evaluate patient or client condition or treatment options\",\n \"guid\": \"a7f7d765-c8ca-42bd-b7a6-8ac184cfefc1\",\n \"score\": 28.82\n },\n ...\n ],\n \"detailed_work_activities\": [\n {\n \"version\": 2,\n \"title\": \"Assist clients with understanding personal problems\",\n \"guid\": \"c1ccb7e1-2ff2-4a3a-b442-ef3b9d264a51\",\n \"score\": 16.47\n },\n {\n \"version\": 2,\n \"title\": \"Counsel clients or patients regarding personal issues or problems\",\n \"guid\": \"663e4b83-9fdb-4170-9888-e00c0731bd59\",\n \"score\": 15.61\n },\n ...\n ]\n\n", "language": "json" } ] } [/block] #### MOCs With the Warrior endpoint, we provide an additional array of the actual MOCs matched in our library, along with metadata about each. Because the same MOC might be used for different things by different service branches, or represent multiple MPCs within a single branch, this array may contain multiple elements. The intent is for this to provide downstream consumers with a means by which to prompt their users for more detail in order to focus the profile match (e.g. "Which of the following Service Branches did you mean?") [block:code] { "codes": [ { "code": "\"mocs\": [\n\t{\n\t\t\"moc\": \"2A554E\",\n\t\t\"mpc\": \"enlisted\",\n\t\t\"service_branch\": \"air force\",\n\t\t\"moc_title\": \"Refuel/Bomber Aircraft Maintenance Journeyman, B-1\"\n },\n ...\n]", "language": "json" } ] } [/block] #### Other Elements See the [original, hierarchical Profiler](https://dev.skillsengine.com/docs/v2competenciesanalyze) for detailed information on the other available elements...
{"_id":"5b3a7fb938c5f700033508b2","category":"5b3a7fb938c5f700033508a2","project":"55e767022942b837005467a2","parentDoc":null,"user":"55e765965d36b32b00256428","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-21T16:15:25.774Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"json","code":"POST /v2/skills/match\n\n{\"text\":\"Provide substance abuse education and counseling for at-risk individuals.\",\"depth\":20,\"cutoff\":5.0,\"socs\":\"21-1023.00,21-1029.00,21-1091.00\", \"similarity_scoring\": true}"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"result\": {\n    \"original_sentence\": \"Provide substance abuse education and counseling for at-risk individuals.\",\n    \"skills\": [\n      {\n        \"version\": 2,\n        \"guid\": \"663e4b83-9fdb-4170-9888-e00c0731bd59\",\n        \"title\": \"Counsel clients or patients regarding personal issues or problems\",\n        \"match_score\": 36.89,\n        \"iwa_guid\": \"4b5db412-c1b8-47e4-9606-03244fdd7880\",\n        \"iwa_title\": \"Counsel others about personal matters\",\n        \"gwa_guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n        \"gwa_title\": \"Provide Consultation and Advice to Others\",\n        \"matched_socs\": [\n          \"21-1029.00\",\n          \"21-1023.00\"\n        ]\n      },\n      {\n        \"version\": 2,\n        \"guid\": \"936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab\",\n        \"title\": \"Refer clients or others to community services or resources\",\n        \"match_score\": 30.74,\n        \"iwa_guid\": \"0cb36e6a-df8d-4ef4-8540-4f62f61b674e\",\n        \"iwa_title\": \"Advise others on products or services\",\n        \"gwa_guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n        \"gwa_title\": \"Provide Consultation and Advice to Others\",\n        \"matched_socs\": [\n          \"21-1029.00\",\n          \"21-1023.00\"\n        ]\n      },\n      {\n        \"version\": 2,\n        \"guid\": \"4c2f53f5-622a-4cbd-859b-02d5e1f099ad\",\n        \"title\": \"Plan programs to address community health issues\",\n        \"match_score\": 28.6,\n        \"iwa_guid\": \"a1b32d32-d65c-433e-be6a-1425d333250f\",\n        \"iwa_title\": \"Develop organizational or program goals or objectives\",\n        \"gwa_guid\": \"14a32eba-d07a-4374-a1c4-1f4868d51fbf\",\n        \"gwa_title\": \"Developing Objectives and Strategies\",\n        \"matched_socs\": [\n          \"21-1091.00\",\n          \"21-1023.00\"\n        ]\n      },\n      ...\n    ]\n  }\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"576969b1f480fb0e004dc004","ref":"","in":"body","required":true,"desc":"single sentence of text to analyze for related work activities. (cannot be more than 50 words)","default":"","type":"string","name":"text"},{"_id":"576969b1f480fb0e004dc003","ref":"","in":"body","required":false,"desc":"adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses","default":"20","type":"int","name":"depth"},{"_id":"576969b1f480fb0e004dc002","ref":"","in":"body","required":false,"desc":"internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition","default":"5.0","type":"double","name":"cutoff"},{"_id":"576969b1f480fb0e004dc001","ref":"","in":"body","required":false,"desc":"(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated 8-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.","default":"","type":"string","name":"socs"},{"_id":"592475fd157cbb3900e07de0","ref":"","in":"body","required":false,"desc":"(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)","default":"false","type":"boolean","name":"similarity_scoring"}],"url":"/v2/skills/match"},"isReference":false,"order":10,"body":"#### Explanation\n\nThe `skills/match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities. The current incarnation of the endpoint allows for a single sentence per request, which is then analyzed and matched against thousands of detailed work activities. The best matches are then scored, sorted, and returned to the requestor in JSON format. \n\nThe intent of this endpoint is to help align text with our skill library, in order to find one or more work activities that match, are similar to, or are related to the text provided. By providing occupational context, the requestor can further shape these results to ensure contextually reasonable skill matches.\n\n#### The `socs` Parameter\n\nThe most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence \"Repair buses\" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect.\n\n**The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.**\n\n#### The `cutoff` Parameter\n\nThe `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a \"final cutoff\" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Data Structure\"\n}\n[/block]\n##### Root Key\nAs with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`).\n\n##### Original Sentence\nThe two second-level siblings in the `/v2/skills/match` response are `original_sentence` and `skills`. The original sentence refers to the actual text sentence sent in the original request -- the sentence we analyzed in order to find matches.\n\n##### Skills\nThe `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements:\n\n        \"version\": 2,\n        \"guid\": \"936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab\",\n        \"title\": \"Refer clients or others to community services or resources\",\n        \"match_score\": 30.74,\n        \"iwa_guid\": \"0cb36e6a-df8d-4ef4-8540-4f62f61b674e\",\n        \"iwa_title\": \"Advise others on products or services\",\n        \"gwa_guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n        \"gwa_title\": \"Provide Consultation and Advice to Others\",\n        \"matched_socs\": [\n          \"21-1029.00\",\n          \"21-1023.00\"\n        ]\n    \n* `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment.\n* `guid` -- the globally unique identifier for this Detailed Work Activity\n* `title` -- the textual title of this Detailed Work Activity\n* `match_score` -- the relevancy score as computed by our matching algorithm\n* `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library\n* `iwa_title` -- the textual title of the parent Intermediate Work Activity\n* `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity)\n* `gwa_title` -- the textual title of the parent General Work Activity\n* `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Limitations\",\n  \"body\": \"The `skills/match` endpoint is limited to analyzing a single sentence of no more than 50 words. Requests that provide a sentence larger than 50 words will return a 422 and an error message.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\",\n  \"title\": \"Authorization Header Required\"\n}\n[/block]","excerpt":"This endpoint analyzes a single sentence and returns multiple related Detailed Work Activities from the SkillsEngine data library.","slug":"v2skillsmatch","type":"post","title":"/v2/skills/match","__v":0,"childrenPages":[]}

post/v2/skills/match

This endpoint analyzes a single sentence and returns multiple related Detailed Work Activities from the SkillsEngine data library.

Body Params

text:
required
string
single sentence of text to analyze for related work activities. (cannot be more than 50 words)
depth:
integer20
adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses
cutoff:
double5.0
internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition
socs:
string
(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated 8-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.
similarity_scoring:
booleanfalse
(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)
#### Explanation The `skills/match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities. The current incarnation of the endpoint allows for a single sentence per request, which is then analyzed and matched against thousands of detailed work activities. The best matches are then scored, sorted, and returned to the requestor in JSON format. The intent of this endpoint is to help align text with our skill library, in order to find one or more work activities that match, are similar to, or are related to the text provided. By providing occupational context, the requestor can further shape these results to ensure contextually reasonable skill matches. #### The `socs` Parameter The most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect. **The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.** #### The `cutoff` Parameter The `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0). [block:api-header] { "type": "basic", "title": "Response Data Structure" } [/block] ##### Root Key As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Original Sentence The two second-level siblings in the `/v2/skills/match` response are `original_sentence` and `skills`. The original sentence refers to the actual text sentence sent in the original request -- the sentence we analyzed in order to find matches. ##### Skills The `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements: "version": 2, "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab", "title": "Refer clients or others to community services or resources", "match_score": 30.74, "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e", "iwa_title": "Advise others on products or services", "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb", "gwa_title": "Provide Consultation and Advice to Others", "matched_socs": [ "21-1029.00", "21-1023.00" ] * `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment. * `guid` -- the globally unique identifier for this Detailed Work Activity * `title` -- the textual title of this Detailed Work Activity * `match_score` -- the relevancy score as computed by our matching algorithm * `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library * `iwa_title` -- the textual title of the parent Intermediate Work Activity * `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity) * `gwa_title` -- the textual title of the parent General Work Activity * `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified. [block:callout] { "type": "danger", "title": "Limitations", "body": "The `skills/match` endpoint is limited to analyzing a single sentence of no more than 50 words. Requests that provide a sentence larger than 50 words will return a 422 and an error message." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



#### Explanation The `skills/match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities. The current incarnation of the endpoint allows for a single sentence per request, which is then analyzed and matched against thousands of detailed work activities. The best matches are then scored, sorted, and returned to the requestor in JSON format. The intent of this endpoint is to help align text with our skill library, in order to find one or more work activities that match, are similar to, or are related to the text provided. By providing occupational context, the requestor can further shape these results to ensure contextually reasonable skill matches. #### The `socs` Parameter The most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect. **The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.** #### The `cutoff` Parameter The `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0). [block:api-header] { "type": "basic", "title": "Response Data Structure" } [/block] ##### Root Key As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Original Sentence The two second-level siblings in the `/v2/skills/match` response are `original_sentence` and `skills`. The original sentence refers to the actual text sentence sent in the original request -- the sentence we analyzed in order to find matches. ##### Skills The `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements: "version": 2, "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab", "title": "Refer clients or others to community services or resources", "match_score": 30.74, "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e", "iwa_title": "Advise others on products or services", "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb", "gwa_title": "Provide Consultation and Advice to Others", "matched_socs": [ "21-1029.00", "21-1023.00" ] * `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment. * `guid` -- the globally unique identifier for this Detailed Work Activity * `title` -- the textual title of this Detailed Work Activity * `match_score` -- the relevancy score as computed by our matching algorithm * `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library * `iwa_title` -- the textual title of the parent Intermediate Work Activity * `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity) * `gwa_title` -- the textual title of the parent General Work Activity * `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified. [block:callout] { "type": "danger", "title": "Limitations", "body": "The `skills/match` endpoint is limited to analyzing a single sentence of no more than 50 words. Requests that provide a sentence larger than 50 words will return a 422 and an error message." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]
{"_id":"5b3a7fb938c5f700033508b3","category":"5b3a7fb938c5f700033508a2","parentDoc":null,"project":"55e767022942b837005467a2","user":"55e765965d36b32b00256428","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-22T17:10:52.588Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"POST /v2/skills/multi_match\n\n{\"sentences\":[\"Weld things together\", \"Use an acetylene torch\", \"Hammer nails into wood\"],\"depth\":20,\"cutoff\":5.0,\"socs\":\"17-2141.00,49-9041.00,49-1011.00,49-9071.00\"}","language":"json"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"result\": [\n    {\n      \"original_sentence\": \"weld things together\",\n      \"skills\": [\n        {\n          \"version\": 2,\n          \"guid\": \"539f8155-091c-4d0e-92ef-87e270b49cad\",\n          \"title\": \"Weld metal structures\",\n          \"match_score\": 79.72,\n          \"iwa_guid\": \"2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5\",\n          \"iwa_title\": \"Join parts using soldering, welding, or brazing techniques\",\n          \"gwa_guid\": \"2e603185-6389-4d71-8789-538d3ff65f04\",\n          \"gwa_title\": \"Handling and Moving Objects\",\n          \"matched_socs\": [\n            \"49-9071.00\",\n            \"49-9041.00\",\n            \"49-1011.00\"\n          ]\n        },\n        {\n          \"version\": 2,\n          \"guid\": \"93acf6aa-60da-42eb-b9a3-378332bee348\",\n          \"title\": \"Weld metal parts and components\",\n          \"match_score\": 38.49,\n          \"iwa_guid\": \"2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5\",\n          \"iwa_title\": \"Join parts using soldering, welding, or brazing techniques\",\n          \"gwa_guid\": \"2e603185-6389-4d71-8789-538d3ff65f04\",\n          \"gwa_title\": \"Handling and Moving Objects\",\n          \"matched_socs\": [\n            \"49-9071.00\",\n            \"49-9041.00\"\n          ]\n        }\n      ]\n    },\n    {\n      \"original_sentence\": \"use an acetylene torch\",\n      \"skills\": [\n        {\n          \"version\": 2,\n          \"guid\": \"539f8155-091c-4d0e-92ef-87e270b49cad\",\n          \"title\": \"Weld metal structures\",\n          \"match_score\": 46.49,\n          \"iwa_guid\": \"2eabe35f-6a7e-4ad2-8f6c-4840ff4924a5\",\n          \"iwa_title\": \"Join parts using soldering, welding, or brazing techniques\",\n          \"gwa_guid\": \"2e603185-6389-4d71-8789-538d3ff65f04\",\n          \"gwa_title\": \"Handling and Moving Objects\",\n          \"matched_socs\": [\n            \"49-9071.00\",\n            \"49-9041.00\",\n            \"49-1011.00\"\n          ]\n        },\n        {\n          \"version\": 2,\n          \"guid\": \"39b619cc-52dd-4132-9caa-d3d0c8db0983\",\n          \"title\": \"Heat material or workpieces to prepare for or complete production\",\n          \"match_score\": 37.69,\n          \"iwa_guid\": \"b56307f4-6963-4591-87c1-a2f3b11491b6\",\n          \"iwa_title\": \"Adjust equipment to ensure adequate performance\",\n          \"gwa_guid\": \"2e603185-6389-4d71-8789-538d3ff65f04\",\n          \"gwa_title\": \"Handling and Moving Objects\",\n          \"matched_socs\": []\n        }\n      ]\n    },\n    {\n      \"original_sentence\": \"hammer nails into wood\",\n      \"skills\": [\n        {\n          \"version\": 2,\n          \"guid\": \"c95af047-703a-4e60-9796-ffba18ae8573\",\n          \"title\": \"Install wooden structural components such as sub flooring, rough framing, or partitions\",\n          \"match_score\": 52.53,\n          \"iwa_guid\": \"3282f5be-69d0-418f-a4fc-9c6831e33301\",\n          \"iwa_title\": \"Build structures\",\n          \"gwa_guid\": \"95cb0aab-48a1-4248-8f15-ce3e2895b289\",\n          \"gwa_title\": \"Performing General Physical Activities\",\n          \"matched_socs\": []\n        },\n        {\n          \"version\": 2,\n          \"guid\": \"38398f36-959a-4598-84fa-6f725b03b909\",\n          \"title\": \"Assemble wood or carpentry products\",\n          \"match_score\": 40.22,\n          \"iwa_guid\": \"b64a3c52-78d6-417d-a803-3e2db6e73b1d\",\n          \"iwa_title\": \"Assemble products or work aids\",\n          \"gwa_guid\": \"2e603185-6389-4d71-8789-538d3ff65f04\",\n          \"gwa_title\": \"Handling and Moving Objects\",\n          \"matched_socs\": []\n        }\n      ]\n    }\n  ]\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"576969b1f480fb0e004dc004","ref":"","in":"body","required":true,"desc":"an array of text sentences to analyze for related work activities. (cannot be more than 20 sentences)","default":"","type":"array_string","name":"sentences"},{"_id":"576969b1f480fb0e004dc003","ref":"","in":"body","required":false,"desc":"adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses","default":"20","type":"int","name":"depth"},{"_id":"576969b1f480fb0e004dc002","ref":"","in":"body","required":false,"desc":"internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition","default":"5.0","type":"double","name":"cutoff"},{"_id":"576969b1f480fb0e004dc001","ref":"","in":"body","required":false,"desc":"(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated eight-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.","default":"","type":"string","name":"socs"},{"_id":"59247620afc7bc0f005fe49b","ref":"","in":"body","required":false,"desc":"(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)","default":"false","type":"boolean","name":"similarity_scoring"}],"url":"/v2/skills/multi_match"},"isReference":false,"order":11,"body":"#### Explanation\n\nThe `skills/multi_match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities in bulk. Unlike the standard `match` endpoint, `multi_match` allows for an array of multiple sentences (up to 20) sent as part of a single request, all of which are then analyzed and matched against thousands of detailed work activities. The best matches for each provided sentence are then scored, sorted, and returned to the requestor in JSON format. \n\n#### The `socs` Parameter\n\nThe most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence \"Repair buses\" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect.\n\n**The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.**\n\n#### The `cutoff` Parameter\n\nThe `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a \"final cutoff\" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Data Format\"\n}\n[/block]\n##### Root Key\nAs with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`).\n\n##### Original Sentences and Skills\nUnlike the `skills/match` endpoint, the multi_match endpoint returns an array of two-key hashes. Each of these hashes represents both the original sentence (from the array of input sentences provided) and then a nested array of skill hashes. These skill hashes follow the same structure as the `skills/match` endpoint...\n\n##### Skills\nThe `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements:\n\n        \"version\": 2,\n        \"guid\": \"936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab\",\n        \"title\": \"Refer clients or others to community services or resources\",\n        \"match_score\": 30.74,\n        \"iwa_guid\": \"0cb36e6a-df8d-4ef4-8540-4f62f61b674e\",\n        \"iwa_title\": \"Advise others on products or services\",\n        \"gwa_guid\": \"abe6cddd-0679-4491-ad7a-a672d72ceffb\",\n        \"gwa_title\": \"Provide Consultation and Advice to Others\",\n        \"matched_socs\": [\n          \"21-1029.00\",\n          \"21-1023.00\"\n        ]\n    \n* `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment.\n* `guid` -- the globally unique identifier for this Detailed Work Activity\n* `title` -- the textual title of this Detailed Work Activity\n* `match_score` -- the relevancy score as computed by our matching algorithm\n* `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library\n* `iwa_title` -- the textual title of the parent Intermediate Work Activity\n* `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity)\n* `gwa_title` -- the textual title of the parent General Work Activity\n* `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Limitations\",\n  \"body\": \"The `skills/multi_match` endpoint is limited to analyzing an array of no more than 20 sentences. Requests that provide more than 20 sentences at once will return a 422 and an error message.\\n\\nIn addition, any individual sentence provided to this endpoint can contain no more than 50 words.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\",\n  \"title\": \"Authorization Header Required\"\n}\n[/block]","excerpt":"This endpoint analyzes a bulk array of multiple sentences and returns an array containing each original sentence paired with multiple related Detailed Work Activities from the SkillsEngine data library.","slug":"v2skillsmulti_match","type":"post","title":"/v2/skills/multi_match","__v":0,"childrenPages":[]}

post/v2/skills/multi_match

This endpoint analyzes a bulk array of multiple sentences and returns an array containing each original sentence paired with multiple related Detailed Work Activities from the SkillsEngine data library.

Body Params

sentences:
required
array of strings
an array of text sentences to analyze for related work activities. (cannot be more than 20 sentences)
depth:
integer20
adjusts the computational effort the matching algorithm will undertake in attempting to find matches; higher values means more processing, but potentially slower responses
cutoff:
double5.0
internal tuning cutoff threshold; adjusts the aggressiveness of relevant skill matching internally prior to final result composition
socs:
string
(comma-separated, order-sensitive, optional but recommended); allows the requestor to provide occupational context for a match attempt by supplying one or more comma-separated eight-digit SOC codes. Providing SOC context will dramatically improve matching results in most cases.
similarity_scoring:
booleanfalse
(optional) 'true' will turn on optional text-similarity scoring, rather than relevance scoring (false by default)
#### Explanation The `skills/multi_match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities in bulk. Unlike the standard `match` endpoint, `multi_match` allows for an array of multiple sentences (up to 20) sent as part of a single request, all of which are then analyzed and matched against thousands of detailed work activities. The best matches for each provided sentence are then scored, sorted, and returned to the requestor in JSON format. #### The `socs` Parameter The most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect. **The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.** #### The `cutoff` Parameter The `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0). [block:api-header] { "type": "basic", "title": "Response Data Format" } [/block] ##### Root Key As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Original Sentences and Skills Unlike the `skills/match` endpoint, the multi_match endpoint returns an array of two-key hashes. Each of these hashes represents both the original sentence (from the array of input sentences provided) and then a nested array of skill hashes. These skill hashes follow the same structure as the `skills/match` endpoint... ##### Skills The `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements: "version": 2, "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab", "title": "Refer clients or others to community services or resources", "match_score": 30.74, "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e", "iwa_title": "Advise others on products or services", "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb", "gwa_title": "Provide Consultation and Advice to Others", "matched_socs": [ "21-1029.00", "21-1023.00" ] * `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment. * `guid` -- the globally unique identifier for this Detailed Work Activity * `title` -- the textual title of this Detailed Work Activity * `match_score` -- the relevancy score as computed by our matching algorithm * `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library * `iwa_title` -- the textual title of the parent Intermediate Work Activity * `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity) * `gwa_title` -- the textual title of the parent General Work Activity * `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified. [block:callout] { "type": "danger", "title": "Limitations", "body": "The `skills/multi_match` endpoint is limited to analyzing an array of no more than 20 sentences. Requests that provide more than 20 sentences at once will return a 422 and an error message.\n\nIn addition, any individual sentence provided to this endpoint can contain no more than 50 words." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



#### Explanation The `skills/multi_match` endpoint allows consumers of the Matcher API to align unstructured skill text to the SkillsEngine library of work activities in bulk. Unlike the standard `match` endpoint, `multi_match` allows for an array of multiple sentences (up to 20) sent as part of a single request, all of which are then analyzed and matched against thousands of detailed work activities. The best matches for each provided sentence are then scored, sorted, and returned to the requestor in JSON format. #### The `socs` Parameter The most important parameter in tuning the results of this endpoint is the `socs` parameter. Via the `socs` parameter, a requestor can provide significant context to the matching algorithms, which in turn use that context to ensure resultant matches are more directly relevant to the occupational domain expected by the requestor. For example, without any context, the sentence "Repair buses" could refer to bus drivers (the automobile) or electronics or computer engineers (a data bus). Without occupational context, our algorithm will do the best it can in finding relevant matches, but _with_ context (provided through the `socs` parameter), consumers of the API can ensure they get more of the matches they expect. **The `socs` parameter takes a list of multiple 8-digit SOC codes and the algorithm weights its contextualization based on the order of that list. That is, the algorithm considers the first SOC in the list to be of higher importance than the last SOC, so be sure to provide your list of SOCs in the proper order.** #### The `cutoff` Parameter The `cutoff` parameter is a means by which the requestor can tune internal cutoffs intrinsic to the matching algorithm. It should be noted that this is NOT a "final cutoff" to redact output with a final relevancy score below X; instead, this tuning parameter changes the aggressiveness with which the matching algorithm seeks to populate the final results. A lower number (5.0) will result in a more diverse set of final matches; a higher number (20.0) will significantly limit the final results. In either case, the final resultant matches' scores will be scaled across a spectrum from 1.0 to 99.0 (and we by default don't return any results with a final scaled score lower than 20.0). [block:api-header] { "type": "basic", "title": "Response Data Format" } [/block] ##### Root Key As with the majority of SkillsEngine endpoints, the root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Original Sentences and Skills Unlike the `skills/match` endpoint, the multi_match endpoint returns an array of two-key hashes. Each of these hashes represents both the original sentence (from the array of input sentences provided) and then a nested array of skill hashes. These skill hashes follow the same structure as the `skills/match` endpoint... ##### Skills The `skills` key has as its value a sorted array of hashes. Each hash in that array represents a single Detailed Work Activity that we have matched with the original sentence, as well as a relevancy score. The skills are returned in order of score, highest relevancy first. Each skill hash includes the following elements: "version": 2, "guid": "936c9e29-9e0a-4c6d-b5ed-c2b0d7da49ab", "title": "Refer clients or others to community services or resources", "match_score": 30.74, "iwa_guid": "0cb36e6a-df8d-4ef4-8540-4f62f61b674e", "iwa_title": "Advise others on products or services", "gwa_guid": "abe6cddd-0679-4491-ad7a-a672d72ceffb", "gwa_title": "Provide Consultation and Advice to Others", "matched_socs": [ "21-1029.00", "21-1023.00" ] * `version` -- the version identifier for this Detailed Work Activity as retrieved from our core library at that moment. * `guid` -- the globally unique identifier for this Detailed Work Activity * `title` -- the textual title of this Detailed Work Activity * `match_score` -- the relevancy score as computed by our matching algorithm * `iwa_guid` -- the globally unique identifier for the Intermediate Work Activity that exists as the parent of this Detailed Work Activity in our core library * `iwa_title` -- the textual title of the parent Intermediate Work Activity * `gwa_guid` -- the globally unique identifier for the Intermediate's parent General Work Activity (the grandparent of the Detailed Work Activity) * `gwa_title` -- the textual title of the parent General Work Activity * `matched_socs` -- an array of 8-digit SOC codes that indicate when a matched skill is associated in our core library with one or more of the contextual SOCs provided in the original request. This array may be empty in the case where no contextual SOCs were provided, or in the case where a relevant skill was found that is _not_ associated in our library with any of the contextual SOCs specified. [block:callout] { "type": "danger", "title": "Limitations", "body": "The `skills/multi_match` endpoint is limited to analyzing an array of no more than 20 sentences. Requests that provide more than 20 sentences at once will return a 422 and an error message.\n\nIn addition, any individual sentence provided to this endpoint can contain no more than 50 words." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]
{"_id":"5b3a7fb938c5f700033508a5","category":"5b3a7fb938c5f700033508a3","user":"55e765965d36b32b00256428","parentDoc":null,"project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-30T17:39:10.945Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"json","code":"POST /v2/topics/related\n\n{\"texts\":[\"ms word\", \"access\", \"dexterity\"], \"socs\":[\"41-3041.00\"]}"}]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"result\": {\n    \"matches\": [\n      {\n        \"dbtype\": \"tool\",\n        \"type\": \"technology\",\n        \"category\": \"Word processing software\",\n        \"guid\": \"390dcef4-73b1-4a74-a599-5cc6364a6f15\",\n        \"title\": \"Microsoft Word\",\n        \"score\": 100,\n        \"matched_tokens\": [\n          \"ms word\",\n          \"microsoft word\",\n          \"word powerpoint\",\n          \"word excel\",\n          \"microsoft\"\n        ]\n      },\n      {\n        \"dbtype\": \"tool\",\n        \"type\": \"technology\",\n        \"category\": \"Data base user interface and query software\",\n        \"guid\": \"e279a735-3791-4db9-8cdf-0927bef4ce95\",\n        \"title\": \"Microsoft Access\",\n        \"score\": 100,\n        \"matched_tokens\": [\n          \"access\"\n        ]\n      },\n      {\n        \"dbtype\": \"characteristic\",\n        \"type\": \"ability\",\n        \"category\": \"ability\",\n        \"guid\": \"2fc00d553639f10728c61da01ff25a98\",\n        \"title\": \"Wrist-Finger Speed\",\n        \"score\": 100,\n        \"matched_tokens\": [\n          \"finger dexterity\"\n        ]\n      },\n      {\n        \"dbtype\": \"characteristic\",\n        \"type\": \"skill\",\n        \"category\": \"skill\",\n        \"guid\": \"37dcca91f219e9b454183c21e1f57e5c\",\n        \"title\": \"Coordination\",\n        \"score\": 100,\n        \"matched_tokens\": [\n          \"eye coordination\"\n        ]\n      },\n      {\n        \"dbtype\": \"tool\",\n        \"type\": \"technology\",\n        \"category\": \"Spreadsheet software\",\n        \"guid\": \"50268cdd-7a8d-43ae-9ade-eadd88e2ff21\",\n        \"title\": \"Microsoft Excel\",\n        \"score\": 85.74,\n        \"matched_tokens\": [\n          \"word excel\",\n          \"microsoft\"\n        ]\n      },\n      {\n        \"dbtype\": \"tool\",\n        \"type\": \"technology\",\n        \"category\": \"Presentation software\",\n        \"guid\": \"463e6da6-c2d4-4afc-8876-92a7786322b4\",\n        \"title\": \"Microsoft PowerPoint\",\n        \"score\": 76.22,\n        \"matched_tokens\": [\n          \"word powerpoint\"\n        ]\n      }\n    ],\n    \"tokens\": [\n      \"ms word\",\n      \"microsoft word\",\n      \"word powerpoint\",\n      \"word excel\",\n      \"microsoft\",\n      \"access\",\n      \"dexterity\",\n      \"manual dexterity\",\n      \"finger dexterity\",\n      \"stamina\",\n      \"eye coordination\",\n      \"hand eye\"\n    ]\n  }\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[{"_id":"576969b1f480fb0e004dc004","ref":"","in":"body","required":true,"desc":"an array of one or more short texts (each less than 4 words, preferably) that will be matched to find related topics and matching SkillsEngine library elements","default":"","type":"array_string","name":"texts"},{"_id":"576969b1f480fb0e004dc001","ref":"","in":"body","required":false,"desc":"(optional but recommended); allows the requestor to provide occupational context for a related topics match by supplying one or more 8-digit SOC codes. Providing SOC context will improve matching and downsample topics likely unrelated to the occupations indicated.","default":"","type":"array_string","name":"socs"}],"url":"/v2/topics/related"},"isReference":false,"order":12,"body":"#### Explanation\n\nOur Expander endpoint provides the requestor with a means to find synonyms and highly-related topics to short phrases they provide. These `tokens` are returned in a standard JSON response, along with an array of rich `matches` from our curated data library when we surface tokens that we already know about. This allows, for example, the ability to match \"ms word\" with \"Microsoft Word\", as well as show that it is closely related to \"Microsoft Office\" in many occupational contexts.\n\nIn general, the topics endpoint works best if provided a small number (3 or less) of very short phrases, themselves consisting of a very small number (3 or less) of words. E.g. `[\"ms word\", \"excel\", \"powerpint\"]` (spelling mistake there is intentional, to show that the neural net is frequently capable of comprehending even misspelled input texts in the same way that a human might).\n\nWe anticipate the use cases around this endpoint to focus on expansion of sparse texts where an author of a resume or job posting may have mentioned certain arbitrary tools, technologies, or characteristics that a human reader would infer to be representative of a much wider list of topics. Expanding the user's text into either a list of raw tokens and/or our canonical library elements can provide downstream matching algorithms with much richer text for keyword matching or other applications.\n\n\n#### The `socs` Parameter\n\nLike many of our endpoints, providing one or more O*NET 8-digit SOCs can help Expander better contextualize the end results, boosting matches that directly relate to the referenced occupations and discarding or downsampling those that do not. While this is an optional parameter, it is highly recommended to get higher-quality results from the endpoint.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Data Structure\"\n}\n[/block]\n##### Root Key\nThe root key in a successful JSON response is `result` (the root key in a failure is `error`).\n\n##### Matches\nIncludes a list of highly-relevant matched elements from our curated library. Currently, this list can include Tools/Techs, Knowledges, Skills, Abilities, and Workplace Essentials. It's important to understand that this list of matches is not all-encompassing of anything that might be related to the input text, but rather provides additional detail for surfaced tokens and phrases that we have additional information about. Especially new technologies or concepts (or things that simply don't fit into our current taxonomy) may not be represented in the `matches` array, even though raw tokens show up for them in the `tokens` array.\n\n##### Tokens\nThis is the raw list of tokens and short phrases surfaced by the neural net that underpins the topic expansion system. This list is not guaranteed to have perfectly clean or grammatically-clear tokens, but rather represents the arrangements of words that the neural net has learned are common insofar as they relate to your input text. For example, \"photoshop\" may surface tokens that reference the exact product, similar products, the parent company of the product, or general concepts around the product, such as \"adobe photoshop\", \"adobe illustrator\", \"indesign\", and two-token phrases like \"photoshop illustrator\" and \"photoshop indesign\", suggesting that the neural net has learned that these words are very often found together in work-related documents. We believe that this 'raw' tokens list can have direct application in matching systems by using these as a hidden list of meta-topics attached on both sides of a matching system (e.g. resumes and job postings).\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Performance Caveat\",\n  \"body\": \"Matching a single word or short phrase generally takes Expander a small fraction of a second. Additional texts provided in the `texts` array increase this latency, as the system has to iterate over and process all of these texts as well as handle an increasingly large set of results. For this reason, we suggest users of Expander experiment with how many phrases they want to send in a single request of the endpoint. In cases where a multi-second delay is acceptable, using one request with many texts may be fine. In other cases, it may be more advantageous to send only one or two phrases at a time and parallelize multiple endpoint requests to get maximum performance for your downstream application.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\",\n  \"title\": \"Authorization Header Required\"\n}\n[/block]","excerpt":"This endpoint analyzes one or more short phrases to find related topics and matching elements from the SkillsEngine core library.","slug":"v2topicsrelated","type":"post","title":"/v2/topics/related","__v":0,"childrenPages":[]}

post/v2/topics/related

This endpoint analyzes one or more short phrases to find related topics and matching elements from the SkillsEngine core library.

Body Params

texts:
required
array of strings
an array of one or more short texts (each less than 4 words, preferably) that will be matched to find related topics and matching SkillsEngine library elements
socs:
array of strings
(optional but recommended); allows the requestor to provide occupational context for a related topics match by supplying one or more 8-digit SOC codes. Providing SOC context will improve matching and downsample topics likely unrelated to the occupations indicated.
#### Explanation Our Expander endpoint provides the requestor with a means to find synonyms and highly-related topics to short phrases they provide. These `tokens` are returned in a standard JSON response, along with an array of rich `matches` from our curated data library when we surface tokens that we already know about. This allows, for example, the ability to match "ms word" with "Microsoft Word", as well as show that it is closely related to "Microsoft Office" in many occupational contexts. In general, the topics endpoint works best if provided a small number (3 or less) of very short phrases, themselves consisting of a very small number (3 or less) of words. E.g. `["ms word", "excel", "powerpint"]` (spelling mistake there is intentional, to show that the neural net is frequently capable of comprehending even misspelled input texts in the same way that a human might). We anticipate the use cases around this endpoint to focus on expansion of sparse texts where an author of a resume or job posting may have mentioned certain arbitrary tools, technologies, or characteristics that a human reader would infer to be representative of a much wider list of topics. Expanding the user's text into either a list of raw tokens and/or our canonical library elements can provide downstream matching algorithms with much richer text for keyword matching or other applications. #### The `socs` Parameter Like many of our endpoints, providing one or more O*NET 8-digit SOCs can help Expander better contextualize the end results, boosting matches that directly relate to the referenced occupations and discarding or downsampling those that do not. While this is an optional parameter, it is highly recommended to get higher-quality results from the endpoint. [block:api-header] { "type": "basic", "title": "Response Data Structure" } [/block] ##### Root Key The root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Matches Includes a list of highly-relevant matched elements from our curated library. Currently, this list can include Tools/Techs, Knowledges, Skills, Abilities, and Workplace Essentials. It's important to understand that this list of matches is not all-encompassing of anything that might be related to the input text, but rather provides additional detail for surfaced tokens and phrases that we have additional information about. Especially new technologies or concepts (or things that simply don't fit into our current taxonomy) may not be represented in the `matches` array, even though raw tokens show up for them in the `tokens` array. ##### Tokens This is the raw list of tokens and short phrases surfaced by the neural net that underpins the topic expansion system. This list is not guaranteed to have perfectly clean or grammatically-clear tokens, but rather represents the arrangements of words that the neural net has learned are common insofar as they relate to your input text. For example, "photoshop" may surface tokens that reference the exact product, similar products, the parent company of the product, or general concepts around the product, such as "adobe photoshop", "adobe illustrator", "indesign", and two-token phrases like "photoshop illustrator" and "photoshop indesign", suggesting that the neural net has learned that these words are very often found together in work-related documents. We believe that this 'raw' tokens list can have direct application in matching systems by using these as a hidden list of meta-topics attached on both sides of a matching system (e.g. resumes and job postings). [block:callout] { "type": "danger", "title": "Performance Caveat", "body": "Matching a single word or short phrase generally takes Expander a small fraction of a second. Additional texts provided in the `texts` array increase this latency, as the system has to iterate over and process all of these texts as well as handle an increasingly large set of results. For this reason, we suggest users of Expander experiment with how many phrases they want to send in a single request of the endpoint. In cases where a multi-second delay is acceptable, using one request with many texts may be fine. In other cases, it may be more advantageous to send only one or two phrases at a time and parallelize multiple endpoint requests to get maximum performance for your downstream application." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



#### Explanation Our Expander endpoint provides the requestor with a means to find synonyms and highly-related topics to short phrases they provide. These `tokens` are returned in a standard JSON response, along with an array of rich `matches` from our curated data library when we surface tokens that we already know about. This allows, for example, the ability to match "ms word" with "Microsoft Word", as well as show that it is closely related to "Microsoft Office" in many occupational contexts. In general, the topics endpoint works best if provided a small number (3 or less) of very short phrases, themselves consisting of a very small number (3 or less) of words. E.g. `["ms word", "excel", "powerpint"]` (spelling mistake there is intentional, to show that the neural net is frequently capable of comprehending even misspelled input texts in the same way that a human might). We anticipate the use cases around this endpoint to focus on expansion of sparse texts where an author of a resume or job posting may have mentioned certain arbitrary tools, technologies, or characteristics that a human reader would infer to be representative of a much wider list of topics. Expanding the user's text into either a list of raw tokens and/or our canonical library elements can provide downstream matching algorithms with much richer text for keyword matching or other applications. #### The `socs` Parameter Like many of our endpoints, providing one or more O*NET 8-digit SOCs can help Expander better contextualize the end results, boosting matches that directly relate to the referenced occupations and discarding or downsampling those that do not. While this is an optional parameter, it is highly recommended to get higher-quality results from the endpoint. [block:api-header] { "type": "basic", "title": "Response Data Structure" } [/block] ##### Root Key The root key in a successful JSON response is `result` (the root key in a failure is `error`). ##### Matches Includes a list of highly-relevant matched elements from our curated library. Currently, this list can include Tools/Techs, Knowledges, Skills, Abilities, and Workplace Essentials. It's important to understand that this list of matches is not all-encompassing of anything that might be related to the input text, but rather provides additional detail for surfaced tokens and phrases that we have additional information about. Especially new technologies or concepts (or things that simply don't fit into our current taxonomy) may not be represented in the `matches` array, even though raw tokens show up for them in the `tokens` array. ##### Tokens This is the raw list of tokens and short phrases surfaced by the neural net that underpins the topic expansion system. This list is not guaranteed to have perfectly clean or grammatically-clear tokens, but rather represents the arrangements of words that the neural net has learned are common insofar as they relate to your input text. For example, "photoshop" may surface tokens that reference the exact product, similar products, the parent company of the product, or general concepts around the product, such as "adobe photoshop", "adobe illustrator", "indesign", and two-token phrases like "photoshop illustrator" and "photoshop indesign", suggesting that the neural net has learned that these words are very often found together in work-related documents. We believe that this 'raw' tokens list can have direct application in matching systems by using these as a hidden list of meta-topics attached on both sides of a matching system (e.g. resumes and job postings). [block:callout] { "type": "danger", "title": "Performance Caveat", "body": "Matching a single word or short phrase generally takes Expander a small fraction of a second. Additional texts provided in the `texts` array increase this latency, as the system has to iterate over and process all of these texts as well as handle an increasingly large set of results. For this reason, we suggest users of Expander experiment with how many phrases they want to send in a single request of the endpoint. In cases where a multi-second delay is acceptable, using one request with many texts may be fine. In other cases, it may be more advantageous to send only one or two phrases at a time and parallelize multiple endpoint requests to get maximum performance for your downstream application." } [/block] [block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]
{"_id":"5b3a7fb938c5f700033508b0","category":"5b3a7fb938c5f700033508a4","parentDoc":null,"user":"55e765965d36b32b00256428","project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-25T14:26:47.894Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"GET /v2/occupations","language":"html"}]},"method":"get","results":{"codes":[{"name":"","code":"{\n  \"result\": {\n    \"occupations\": [\n\t\t\t{\n        \"guid\":\"4f1e9cd3-c039-40b1-acc2-e61709440f41\",\n        \"soc\":\"11-1011.00\",\n        \"title\":\"Chief Executives\",\n        \"short_title\":\"Chief Executives\",\n        \"description\":\"Determine and formulate policies and provide overall direction of companies or private and public sector organizations within guidelines set up by a board of directors or similar governing body. Plan, direct, or coordinate operational activities at the highest level of management with the help of subordinate executives and staff managers.\"\n      },\n      ...\n    ]\n  }\n}","language":"json","status":200}]},"settings":"","auth":"required","params":[],"url":"/v2/occupations"},"isReference":false,"order":13,"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\",\n  \"title\": \"Authorization Header Required\"\n}\n[/block]","excerpt":"Returns an array of all known occupations with only first-level data, including SOCs, titles, and descriptions.","slug":"testinput","type":"get","title":"/v2/occupations","__v":0,"childrenPages":[]}

get/v2/occupations

Returns an array of all known occupations with only first-level data, including SOCs, titles, and descriptions.

[block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.", "title": "Authorization Header Required" } [/block]
{"_id":"5b3a7fb938c5f700033508b1","category":"5b3a7fb938c5f700033508a4","user":"55e765965d36b32b00256428","parentDoc":null,"project":"55e767022942b837005467a2","version":"5b3a7fb938c5f700033508b4","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-17T17:14:03.065Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"GET /occupations/soc_codes?soc_codes=13-2011,15-2031,15-2011\n\nGET /occupations/soc_codes?soc_codes=13-2011,15-2031,15-2011&state_code=TX","language":"html"}]},"method":"get","results":{"codes":[{"code":"{\n  \"result\": {\n    \"occupations\": [\n      {\n        \"stfips_code\": 35,\n        \"soc_code\": \"13-2011\",\n        \"title\": \"Accountants and Auditors\",\n        \"short_title\": \"Accountants and Auditors\",\n        \"region_code\": \"NM\",\n        \"base_year\": 2012,\n        \"jobs_base\": 5980,\n        \"projection_year\": 2022,\n        \"jobs_projection_total\": 6520,\n        \"jobs_projection_change\": 540,\n        \"jobs_percent_change\": 9.0,\n        \"average_annual_openings\": 230,\n        \"hourly_mean_wage\": 28.97,\n        \"hourly_median_wage\": 26.32,\n        \"annual_mean_wage\": 60250.0,\n        \"annual_median_wage\": 54740.0\n      }\n    ]\n  }\n}","language":"json","status":200,"name":""}]},"settings":"","auth":"required","params":[{"_id":"56c4aa5b116c0d21000bcf3a","ref":"","in":"query","required":true,"desc":"a comma-separated list of SOCs","default":"","type":"string","name":"soc_codes"},{"_id":"56c4aa5b116c0d21000bcf39","ref":"","in":"query","required":false,"desc":"an optional 2-letter state code that will filter results to only include statistical data for the specified state","default":"","type":"string","name":"state_code"}],"url":"/v2/occupations/soc_codes"},"isReference":false,"order":14,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"**`soc_codes`** must be comma-separated and may be either 6-digit or 8-digit codes. Note that, because they are more granular, 8-digit codes may result in less-detailed results than their 6-digit parents.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Authorization Header Required\",\n  \"body\": \"This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`.\"\n}\n[/block]","excerpt":"Returns an array of occupations with associated information and statistical data based on the O*NET SOCs (Standard Occupational Codes) provided in the request.","slug":"occupationssoc_codes","type":"get","title":"/v2/occupations/soc_codes","__v":0,"childrenPages":[]}

get/v2/occupations/soc_codes

Returns an array of occupations with associated information and statistical data based on the O*NET SOCs (Standard Occupational Codes) provided in the request.

Query Params

soc_codes:
required
string
a comma-separated list of SOCs
state_code:
string
an optional 2-letter state code that will filter results to only include statistical data for the specified state
[block:callout] { "type": "info", "body": "**`soc_codes`** must be comma-separated and may be either 6-digit or 8-digit codes. Note that, because they are more granular, 8-digit codes may result in less-detailed results than their 6-digit parents." } [/block] [block:callout] { "type": "warning", "title": "Authorization Header Required", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "info", "body": "**`soc_codes`** must be comma-separated and may be either 6-digit or 8-digit codes. Note that, because they are more granular, 8-digit codes may result in less-detailed results than their 6-digit parents." } [/block] [block:callout] { "type": "warning", "title": "Authorization Header Required", "body": "This endpoint requires an `Authorization` header attribute with a valid `Bearer <access-token>`." } [/block]