├── assets ├── dsad.png ├── dsam.png ├── authz.png ├── RoutingLayerErrorCodes.pdf └── ExternalClientCredentials.pdf ├── .gitignore ├── KeywordStuffingDetector.md ├── JobToCandidateRecs.md ├── ProgrammaticPricing.md ├── Data └── GeocodingServiceSupportedLanguages.md ├── ProgrammaticFilterService.md ├── JobLevel.md ├── MajorNormalization.md ├── CompanyJobTitles.md ├── SchoolNormalization.md ├── VirusScanner.md ├── TaxonomyService.md ├── CompanyWorkActivities.md ├── ResolvedTitle.md ├── CompanyJobDescription.md ├── CompanyAddress.md ├── ApplicantQualityScore.md ├── Optimizer.md ├── CaroteneSkills.md ├── Versioning.md ├── EstimatedApplications.md ├── SemanticOverrides.md ├── SalaryService.md ├── SemanticAutocomplete.md ├── CompanyNormalization.md ├── LikelihoodToRespond.md ├── PlaceAutocomplete.md ├── JobTitle.md ├── PlaceDetails.md ├── Skills.md ├── PlaceAutocompleteDetails.md ├── README.md ├── Autocomplete.md ├── NextJob.md ├── SemanticSearchV2.md ├── JobParseAndNormalize.md ├── JobRecommendationService.md └── Geocoding.md /assets/dsad.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/careerbuilder/DataScienceAPIDocumentation/HEAD/assets/dsad.png -------------------------------------------------------------------------------- /assets/dsam.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/careerbuilder/DataScienceAPIDocumentation/HEAD/assets/dsam.png -------------------------------------------------------------------------------- /assets/authz.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/careerbuilder/DataScienceAPIDocumentation/HEAD/assets/authz.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | target 2 | .classpath 3 | .project 4 | .settings 5 | cids.csv 6 | downloads/ 7 | *.iml 8 | .DS_Store 9 | .idea/ 10 | -------------------------------------------------------------------------------- /assets/RoutingLayerErrorCodes.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/careerbuilder/DataScienceAPIDocumentation/HEAD/assets/RoutingLayerErrorCodes.pdf -------------------------------------------------------------------------------- /assets/ExternalClientCredentials.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/careerbuilder/DataScienceAPIDocumentation/HEAD/assets/ExternalClientCredentials.pdf -------------------------------------------------------------------------------- /KeywordStuffingDetector.md: -------------------------------------------------------------------------------- 1 | 2 | · Accepts GET and POST requests 3 | · Accepts title, desc, and reqs parameters (must provide at least one) 4 | · Returns a JSON response data with a single contains_spam element (1.0 for true, 0.0 for false) 5 | 6 | An example request: https://wwwtest.api.careerbuilder.com/core/tagging/spamdetector?title=engineer&desc=solve%20hard%20problems&reqs=four%20year%20degree 7 | 8 | And its response: 9 | 10 | { 11 | "data": { 12 | "contains_spam": "0.0" 13 | } 14 | } 15 | 16 | #Versioning 17 | ----------- 18 | The current version is 1.0. The data returned is versioned. 19 | 20 | Our general versioning strategy is available [here](/Versioning.md). 21 | -------------------------------------------------------------------------------- /JobToCandidateRecs.md: -------------------------------------------------------------------------------- 1 | Job To Candidate Recommendation Service 2 | ========================================= 3 | 4 | - [Summary](#summary) 5 | - [Request](#request) 6 | - [Response](#response) 7 | 8 | ## Summary 9 | DSAD's job-to-candidate-recs service accepts POST requests which specify a `job_id`, and will return a list of `Candidate` including their `document_id`, `data_source`, `first_name`, `last_name`, `email` and `quality_score`. 10 | 11 | The route: 12 | - Staging: https://wwwtest.api.careerbuilder.com/core/jobtocandidate/recs 13 | - Produs: https://api.careerbuilder.com/core/jobtocandidate/recs 14 | 15 | ## Request 16 | 17 | HTTP method: POST (form or JSON) 18 | 19 | Parameters: 20 | 21 | * `job_id` (required) : the unique id of a job 22 | 23 | Example: 24 | ``` 25 | { 26 | "job_id": "j3322" 27 | } 28 | ``` 29 | ## Response 30 | example: 31 | ``` 32 | { 33 | "data": [ 34 | { 35 | "document_id": "d111", 36 | "data_source": "data_source", 37 | "first_name": "kitty2", 38 | "last_name": "hello2", 39 | "email": "hehe2@email.com", 40 | "quality_score": 99.0 41 | }, 42 | { 43 | "document_id": "d777", 44 | "data_source": "data_source", 45 | "first_name": "kitty3", 46 | "last_name": "hello3", 47 | "email": "hehe3@email.com", 48 | "quality_score": 77.0 49 | } 50 | ] 51 | } 52 | ``` 53 | 54 | -------------------------------------------------------------------------------- /ProgrammaticPricing.md: -------------------------------------------------------------------------------- 1 | Programmatic Pricing 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Programmatic Pricing service provides an estimated price for a job based on OnetCode and a location (not required). Programmatic Pricing is available at 15 | `/core/programmatic-pricing`. 16 | 17 | 18 | ## Request Structure 19 | 20 | | Field name | Type |Required| 21 | |:------------------|:-------|:-------| 22 | |`onet_id` | string | Y | 23 | |`onet_version` | string | Y | 24 | |`locality` | string | N | 25 | |`admin_area_1` | string | N | 26 | 27 | ```json 28 | { 29 | "onet_id": "29-1141.00", 30 | "onet_version": "ONET17", 31 | "locality": "los angeles", 32 | "admin_area_1": "ca" 33 | } 34 | ``` 35 | Allowed method is :"POST" 36 | 37 | The ONet version currently supported is listed in the [Versioning](#versioning) 38 | section of this document and is subject to change over time. Any removal of support for a taxonomy 39 | version will be implemented as a versioned change to the API itself. 40 | 41 | 42 | ## Response Structure 43 | Response consist of a float of `price`. 44 | 45 | ```json 46 | { 47 | "data": { 48 | "price": 21.88 49 | } 50 | } 51 | ``` 52 | 53 | ## Versioning 54 | The current version of the service is 1.0. 55 | 56 | Currently ONet17 classification is available. 57 | 58 | 59 | Our general versioning strategy is available [here](/Versioning.md). 60 | -------------------------------------------------------------------------------- /Data/GeocodingServiceSupportedLanguages.md: -------------------------------------------------------------------------------- 1 | Our service uses Google's Geocoding API and thus supports the same set of languages. Google's list of accepted languages can be found [here](https://developers.google.com/maps/faq#using-google-maps-apis) and is also provided below for convenience. All codes listed are compliant with the ISO-639-1 standard, except for languages which specify a country or region (such as "English (Australian") and "Portuguese (Brazil)") which have no ISO code, and for Chinese, which is simply referred to as "Chinese" with code "zh" in the ISO standard. Use the **culture=** query parameter with the appropriate culture code to request geocoding results in the desired language. 2 | 3 | Note: that cache overrides will not be provided for languages other than English. 4 | 5 | |**Code**|**Language**| 6 | |:-------:|:-----------:| 7 | |ar|Arabic| 8 | |bg|Bulgarian| 9 | |bn|Bengali| 10 | |ca|Catalan| 11 | |cs|Czech| 12 | |da|Danish| 13 | |de|German| 14 | |el|Greek| 15 | |en|English| 16 | |en-AU|English (Australian)| 17 | |en-GB|English (Great Britain)| 18 | |es|Spanish| 19 | |eu|Basque| 20 | |fa|Farsi| 21 | |fi|Finnish| 22 | |fil|Filipino| 23 | |fr|French| 24 | |gl|Galician| 25 | |gu|Gujarati| 26 | |hi|Hindi| 27 | |hr|Croatian| 28 | |hu|Hungarian| 29 | |id|Indonesian| 30 | |it|Italian| 31 | |iw|Hebrew| 32 | |ja|Japanese| 33 | |kn|Kannada| 34 | |ko|Korean| 35 | |lt|Lithuanian| 36 | |lv|Latvian| 37 | |ml|Malayalam| 38 | |mr|Marathi| 39 | |nl|Dutch| 40 | |no|Norwegian| 41 | |pl|Polish| 42 | |pt|Portuguese| 43 | |pt-BR|Portuguese (Brazil)| 44 | |pt-PT|Portuguese (Portugal)| 45 | |ro|Romanian| 46 | |ru|Russian| 47 | |sk|Slovak| 48 | |sl|Slovenian| 49 | |sr|Serbian| 50 | |sv|Swedish| 51 | |ta|Tamil| 52 | |te|Telugu| 53 | |th|Thai| 54 | |tl|Tagalog| 55 | |tr|Turkish| 56 | |uk|Ukrainian| 57 | |vi|Vietnamese| 58 | |zh-CN|Chinese (Simplified)| 59 | |zh-TW|Chinese (Traditional)| 60 | -------------------------------------------------------------------------------- /ProgrammaticFilterService.md: -------------------------------------------------------------------------------- 1 | Programmatic Filter Service 2 | ============= 3 | 4 | Table of Contents 5 | _________ 6 | - [Summary](#summary) 7 | - [Request Information](#request-information) 8 | - [Sample Response](#sample-response) 9 | 10 | # Summary 11 | This service takes a location and job title and/or description. The job title and/or description are used to call `Job Title` service. `Job Title` returns an onet id, which is then used to find the item in the ProgrammaticFilter table in DynamoDB with a `pk` key composed of the `onet_id` and location info (from request). 12 | 13 | If the item with matched key is in the table, that means that the amount of active jobs in the area is not over the threshold and we can post more job postings with the same `onet_id` for this area. In this case, 14 | we return `true` for response. If it is not in the table, we return `false`. 15 | 16 | # Request Information 17 | 18 | HTTP method: GET or POST (form or JSON) 19 | 20 | Parameters: 21 | 22 | * `title` (required if description is empty) : job title 23 | * `description` (required if title is empty) : job description 24 | * `locality`: The locality, such as the city or neighborhood, that corresponds to an address. 25 | * `admin_area`: The subdivision name in the country or region for an address. 26 | 27 | ``` 28 | curl --location --request POST 'https://api.careerbuilder.com/core/programmatic/filter' \ 29 | -H 'Accept: application/json;version=1.0' \ 30 | -H 'Authorization: ' \ 31 | -H 'Content-Type: application/json' \ 32 | --data-raw '{ 33 | "title": "material scientist", 34 | "locality": "WAUNA", 35 | "admin_area": "WA" 36 | }' 37 | ``` 38 | This service will call jobtitle, so please get a valid jwt token to send request when running locally. 39 | 40 | # Sample Response 41 | ``` 42 | { 43 | "data": { 44 | "is_over_threshold": true 45 | } 46 | } 47 | ``` 48 | -------------------------------------------------------------------------------- /JobLevel.md: -------------------------------------------------------------------------------- 1 | Job Level Classifier 2 | ================= 3 | 4 | 5 | Table of Contents 6 | _______________ 7 | 8 | - [Summary](#summary) 9 | - [Input Requirements](#input-requirements) 10 | - [Sample Response](#sample-response) 11 | - [Response Information](#response-information) 12 | - [Versioning](#versioning) 13 | 14 | 15 | # Summary 16 | 17 | This service will attempt to determine the level (i.e. seniority, expected experience) of a job based on its title. It will return a value from 1 to 5, along with a brief description. 18 | 19 | The service is located at https://api.careerbuilder.com/core/tagging/joblevel. As usual, you will need OAuth credentials to use this service. 20 | 21 | 22 | # Input Requirements 23 | 24 | HTTP method: GET or POST Parameters (query/form): 25 | * title: (required) the job title. 26 | 27 | Here is an example input: 28 | 29 | ``` 30 | HTTP GET 31 | Accept: application/json;version=1.0 32 | https://api.careerbuilder.com/core/tagging/joblevel?title=software engineer 33 | ``` 34 | 35 | # Sample Response 36 | ``` 37 | { 38 | "data": { 39 | "level": 3, 40 | "description": "Experienced (non-Manager)" 41 | } 42 | } 43 | ``` 44 | 45 | # Response Information 46 | 47 | The output will always contain the following three fields for a valid input: 48 | 49 | text: the provided title 50 | 51 | level: an integer between 1 and 5 indicating the job’s level 52 | 53 | description: a brief description corresponding to the level 54 | 55 | Following are all of the possible level + description pairs: 56 | 57 | | Level | Description | 58 | |-------|------------------------------------------------------| 59 | | 1 | Internship | 60 | | 2 | Entry Level | 61 | | 3 | Experienced (non-Manager) | 62 | | 4 | Manager (Manager, Supervisor of Staff) | 63 | | 5 | Executive (VP, SVP, Department Head, President, etc) | 64 | 65 | # Versioning 66 | ----------- 67 | Our general versioning strategy is available [here](/Versioning.md). 68 | 69 | Please email DataScienceApplicationDevelopment@careerbuilder.com if you have any questions or concerns. 70 | -------------------------------------------------------------------------------- /MajorNormalization.md: -------------------------------------------------------------------------------- 1 | Major Normalization Service 2 | ============= 3 | 4 | Table of Contents 5 | _________ 6 | - [Request Information](#request-information) 7 | - [Response](#response) 8 | - [Versioning](#versioning) 9 | 10 | 11 | 12 | Request Information 13 | ----- 14 | 15 | HTTP method: GET or POST 16 | 17 | Parameters (query/form): 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 |
Request Fields
NameRequiredComment
major_name
trueA string containing the major name to be normalized
35 | 36 | Example: https://api.careerbuilder.com/core/normalizedmajor?major_name=electrical%20engineering 37 | 38 | 39 | Response 40 | ----- 41 | 42 | The response contains `normalized_majors` and `data_version` nodes under the `data` node. `normalized_majors` is an array of normalized major json objects and each object may contain the following fields. 43 | 44 | 45 | | Name | Always present | Type | 46 | |----------------|----------------|--------| 47 | | normalized_name| Yes | string | 48 | | cip_code | No | string | 49 | | confidence | Yes | number | 50 | 51 | These normalized majors are ordered by the confidence score. Confidence scores range from [0, 1]. 52 | 53 | Sample Response 54 | 55 | ``` 56 | { 57 | "data": { 58 | "normalized_majors": [ 59 | { 60 | "normalized_name": "Electrical Engineering", 61 | "cip_code": "15.001", 62 | "confidence": 0.8885 63 | }, 64 | { 65 | "normalized_name": "Double Major", 66 | "confidence": 0.05077937173529645 67 | }, 68 | ], 69 | "data_version": "1.0.0" 70 | } 71 | } 72 | ``` 73 | 74 | 75 | Versioning 76 | ----------- 77 | The data that backs the Major Normalization Service is versioned. There is a "data version" field in the response that contains the current version. 78 | 79 | Our general versioning strategy is available [here](/Versioning.md). 80 | -------------------------------------------------------------------------------- /CompanyJobTitles.md: -------------------------------------------------------------------------------- 1 | Company Job Titles 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Company Job Titles service provides a list of job titles (along with their ONet and Carotene 15 | classifications) that are personalized for a given company. Company Job Titles is available at 16 | `/core/company/jobtitles`. 17 | 18 | 19 | ## Request Structure 20 | Requests consist of a `company_id` and `country` string: 21 | 22 | ```json 23 | { 24 | "company_id": "NC6623058c-2e0b-4998-ac4a-72e478e91337", 25 | "country": "us", 26 | "carotene_version": "carotenev3", 27 | "onet_version": "onet17" 28 | } 29 | ``` 30 | 31 | `company_id` is required. `country` is optional and defaults to 'US' if not specified. Currently 32 | supported countries are: 33 | 34 | - US 35 | - UK 36 | 37 | The ONet and Carotene versions currently supported are listed in the [Versioning](#versioning) 38 | section of this document and are subject to change over time. Any removal of support for a taxonomy 39 | version will be implemented as a versioned change to the API itself. 40 | 41 | 42 | ## Response Structure 43 | Response consist of a list of `job_titles` where each item contains a `job_title` string and 44 | its associated ONet and Carotene classification code. 45 | 46 | ```json 47 | { 48 | "data": { 49 | "job_titles": [ 50 | { 51 | "job_title": "Clerical Assistant", 52 | "onet_code": "43-4051.00", 53 | "carotene_code": "43.106" 54 | }, 55 | { 56 | "job_title": "Commercial Account Manager / Department Manager", 57 | "onet_code": "41-3021.00", 58 | "carotene_code": "41.12" 59 | } 60 | ] 61 | } 62 | } 63 | ``` 64 | 65 | ## Versioning 66 | The current version of the service is 1.0. 67 | 68 | Currently ONet17 and Carotene v3 classifications are available. 69 | 70 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 71 | 72 | Our general versioning strategy is available [here](/Versioning.md). 73 | -------------------------------------------------------------------------------- /SchoolNormalization.md: -------------------------------------------------------------------------------- 1 | SchoolNormalizationService 2 | ============= 3 | 4 | Table of Contents 5 | _________ 6 | - [Request Information](#request-information) 7 | - [Sample Response](#sample-response) 8 | - [Versioning](#versioning) 9 | 10 | 11 | 12 | # Request Information 13 | 14 | 15 | HTTP method: GET or POST 16 | Parameters (query/form): 17 | - query (required) : The educational institution information to be queried. 18 | - country (optional) : 2 digit ISO country code of educational institution. 19 | - school_level (optional) : SECONDARY, POSTSECONDARY, ANY. 20 | 21 | Example: https://api.careerbuilder.com/core/normalizedschools?query=georgia%20tech&country=us 22 | 23 | # Sample Response 24 | 25 | 26 | ``` 27 | { 28 | "data": { 29 | "normalized_schools": [ 30 | { 31 | "normalized_school_name": "Georgia Institute of Technology", 32 | "id": "53bff579e4b04710d09fa98d", 33 | "confidence": 1.0, 34 | "country": "US", 35 | "city": "Atlanta", 36 | "state": "GA", 37 | "ipeds_id": "139755", 38 | "ipeds_name": "Georgia Institute of Technology-Main Campus" 39 | "school_level": "POSTSECONDARY" 40 | } 41 | ] 42 | } 43 | } 44 | ``` 45 | 46 | 47 | # Response Information 48 | 49 | The response returns a single data node which contains a list of normalized schools. These normalized schools are ordered by the confidence score. Each normalized shool has a normalized school name (string), a unique ID (string), a confidence (double), a country (string), a city (string), a state (string), an ipeds_id (string), an ipeds_name (string) and a school_level (string). Confidence scores range from 0.0 to 1.0. school_level can be POSTSECONDARY or SECONDARY. 50 | 51 | Regarding the two fields ipeds_id and ipeds_name, ipeds stands for Integrated Postsecondary Education Data System. The unique id and name are assigned to every school registered with the National Center for Education Statistics. 52 | 53 | # Versioning 54 | ----------- 55 | The response from the School Normalization Service is versioned with the current version being 1.0. The data set used to perform the normalization is unversioned. 56 | 57 | Our general versioning strategy is available [here](/Versioning.md). 58 | -------------------------------------------------------------------------------- /VirusScanner.md: -------------------------------------------------------------------------------- 1 | VirusScanner 2 | ============ 3 | 4 | #### Contents 5 | 6 | - [Description](#description) 7 | - [Request](#request) 8 | - [Request Structure](#request-structure) 9 | - [Sample Request](#sample-request) 10 | - [Response Structure](#response-structure) 11 | - [Versioning](#versioning) 12 | 13 | ## Description 14 | 15 | This service runs advanced antivirus scans on any file type. We poll Avira's update server every five minutes to ensure that the service is as up to date as possible. 16 | 17 | The libraries that these virus scans are based on are regularly updated by Avira - sometimes as many as 20 or 30 times a day. We recommend regular reflows of data to ensure that your data security is as up to date as possible. All files that return **is_safe = false** should be immediately quarantined and the source of the data should be investigated. 18 | 19 | ## Request 20 | 21 | A Virus Scanner request is simply the base64 string representation of a file to be scanned. The VS API accepts GET and POST requests, however we recommend using POSTs to avoid the request size limitations inherent to GET requests. 22 | 23 | ## Request Structure 24 | 25 | | Parameter | Description | 26 | |------------|-------------| 27 | | document | Required. The base64 string representation of a file to be scanned. | 28 | 29 | ## Sample Request 30 | 31 | A sample request on the API tester page can be found [here](https://apimanagement.cbplatform.link/#routes/tester?preURL=https%3A%2F%2Fwwwtest.api.careerbuilder.com%2F&postURL=core%2Fvirusscanner&method=post&contentType=application%2Fx-www-form-urlencoded&acceptType=application%2Fjson&version=default®ion=staging&flow=client_credentials&userDid=&accountDid=&headers=&body=document%3DSGVsbG8gV29ybGQ%3D) 32 | 33 | ## Response Structure 34 | 35 | All responses with an HTTP status of 200 will consist of a JSON object with a top-level "data" node containing the following elements: 36 | 37 | | Field | Description | 38 | |----------|-------------| 39 | | is_safe | A **boolean** value to quickly tell you whether or not the document is believed to contain a virus. | 40 | | virus_definition | A **string** value that will always be returned. If no virus is found, this will say "200 OK" - if a virus is found, this field will contain more specific information about the nature of the virus. | 41 | 42 | ## Versioning 43 | The current API version is 1.0. The data returned from the service is unversioned. 44 | 45 | Our general versioning strategy is available [here](/Versioning.md). 46 | -------------------------------------------------------------------------------- /TaxonomyService.md: -------------------------------------------------------------------------------- 1 | Taxonomy Service 2 | ============= 3 | 4 | Table of Contents 5 | _________ 6 | - [Request Information](#request-information) 7 | - [Response Information](#response-information) 8 | - [Sample Response](#sample-response) 9 | - [Available Taxonomies](#available-taxonomies) 10 | - [Versioning](#versioning) 11 | 12 | 13 | 14 | # Request Information 15 | 16 | 17 | HTTP method: GET 18 | Parameters: The only parameter accepted by this service is the name of the desired taxonomy, provided as part of the URL path. Taxonomy names are case-sensitive and must be entered in lowercase. 19 | 20 | https://api.careerbuilder.com/core/taxonomy/ {[Desired Taxonomy](#available-taxonomies)} / 21 | 22 | Example: https://api.careerbuilder.com/core/taxonomy/carotenev1 23 | 24 | 25 | # Response Information 26 | 27 | The response returns a single data node which maps each language code supported by the taxonomy to a list of the taxonomy's elements for that language. 28 | 29 | 30 | |Response Item|Always Returned|Description| 31 | |----------|----------|-------------| 32 | | id | X | The unique identifier of the taxonomy entry | 33 | | title | X | The title of the taxonomy entry | 34 | | description | | A brief description for the taxonomy entry | 35 | | type | | Describes the taxonomy entry's type | 36 | | normalized name | | The normalized name for the skill title | 37 | 38 | 39 | # Sample Response 40 | 41 | 42 | ``` 43 | { 44 | "data": { 45 | "en": [ 46 | { 47 | "id":"0", 48 | "title":"Title0", 49 | "description":"Description0", 50 | "type":"type" 51 | "normalized_name":"Normalized Name" 52 | }, 53 | { 54 | "id":"1", 55 | "title":"Title1", 56 | "description":"Description1", 57 | "type":"type" 58 | "normalized_name":"Normalized Name" 59 | } 60 | ] 61 | } 62 | } 63 | ``` 64 | 65 | 66 | # Available Taxonomies 67 | ----------- 68 | - onet15 69 | - onet17 70 | - carotenev1 71 | - carotenev2 72 | - carotenev2_2 73 | - carotenev3 74 | - carotenev3_1 75 | - skillsv4 76 | - skillsv5 77 | - skillsv8 78 | - naics2007 79 | 80 | 81 | 82 | # Versioning 83 | ----------- 84 | The response from the Taxonomy Service is versioned with the current version being 1.0. The data sets retrieved are also versioned. These data sets are upgraded at will in order to improve their accuracy. Requests made to this service will always use the latest version of the requested data set. 85 | 86 | Our general versioning strategy is available [here](/Versioning.md). 87 | -------------------------------------------------------------------------------- /CompanyWorkActivities.md: -------------------------------------------------------------------------------- 1 | Company Work Activities 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Company Work Activities service provides a list of work activities associated with a 15 | `company_id` and `carotene_id` or `onet_id`. Company Work Activities is available at 16 | `/core/company/workactivities`. 17 | 18 | ## Request Structure 19 | 20 | Requests consist of a `company_id` string, at least one of `carotene_id` string or 21 | `onet_id` string, and a `carotene_version` string (required if `carotene_id` is present) and 22 | `onet_version` string (required if `onet_id` is present). 23 | 24 | ```json 25 | { 26 | "company_id": "NCf01eccfd-78f5-43e5-98a1-9d6415ea4e7a", 27 | "carotene_id": "51.31", 28 | "carotene_version": "carotenev3", 29 | "onet_id": "53-6041.00", 30 | "onet_version": "onet17" 31 | } 32 | 33 | ``` 34 | 35 | The ONet and Carotene versions currently supported are listed in the [Versioning](#versioning) 36 | section of this document and are subject to change over time. Any removal of support for a taxonomy 37 | version will be implemented as a versioned change to the API itself. 38 | 39 | ## Response Structure 40 | 41 | The response contains a list of work activities associated with the requested `company_id` and 42 | one or both of `carotene_id` and `onet_id`. 43 | 44 | ```json 45 | { 46 | "data": { 47 | "onet_work_activities": [ 48 | { 49 | "activity": "Review work orders or schedules to determine operations or procedures." 50 | }, 51 | { 52 | "activity": "Develop program goals or plans." 53 | }, 54 | { 55 | "activity": "Monitor surroundings to detect potential hazards." 56 | } 57 | ], 58 | "carotene_work_activities": [ 59 | { 60 | "activity": "Specialize in skilled trades" 61 | }, 62 | { 63 | "activity": "Staff through aerotek commercial staffing, a division of aerotek" 64 | }, 65 | { 66 | "activity": "Recruit and screens professionals in areas cnc machining" 67 | } 68 | ] 69 | } 70 | } 71 | ``` 72 | ## Versioning 73 | The current version of the service is 1.0. 74 | 75 | Currently ONet17 and Carotene v3 classifications are available. 76 | 77 | Version must be specified in the Accept header. E.g. ```application/json;version=1.0```. 78 | 79 | Our general versioning strategy is available [here](/Versioning.md). -------------------------------------------------------------------------------- /ResolvedTitle.md: -------------------------------------------------------------------------------- 1 | # Resolved Title Service 2 | 3 | **URL:** https://www.api.careerbuilder.com/core/classifier/resolvedtitle 4 | 5 | This endpoint supports the both HTTP/GET and HTTP/POST methods. 6 | 7 | ## Request 8 | 9 | ### Request Body Example: 10 | 11 | ```json 12 | { 13 | "target_titles": "Software Engineer|Database Administrator|Systems Administrator|Java Software Developer", 14 | "raw_title": "Java developer", 15 | "raw_description": "Come write some java code and do other stuff I guess maybe." 16 | } 17 | ``` 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 |
Request Fields
NameRequiredComment
target_titles
trueA pipe delimited list of possible titles to resolve to. A single title may be supplied if the user simply wishes to test whether an input is a good match for a specified title.
raw_title
trueThe title of the job offer to be classified.
raw_description
falseThe description of the job offer, possibly empty.
44 | 45 | ### Version Parameter: 46 | 47 | *Resolved Title Service* is currently on version 1.0. Version **MUST BE** specified in the Accept header (Ex. `Accept:application/json;version=1.0`). 48 | 49 | ## Response 50 | 51 | #### Sample Response: 52 | ```json 53 | { 54 | "data": { 55 | "title": "Network engineer", 56 | "confidence": 1 57 | } 58 | } 59 | ``` 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 |
Response Fields
NameComment
title
The best match for rawTitle, selected from targetTitles. If no good match is found, this field will contain the string "No good match".
confidence
 The classifier's confidence factor for the assignment. This is a normalized float value [0,1] but without any scale or reference point. It is used for ordering matches by the classifier but should not be used for thresholding. This field will be absent if no good match is found.
77 | 78 | ## Versioning 79 | ----------- 80 | ResolvedTitle is currently on version 1.0, and the data returned from this API is versioned. 81 | 82 | Our general versioning strategy is available [here](/Versioning.md). 83 | 84 | -------------------------------------------------------------------------------- /CompanyJobDescription.md: -------------------------------------------------------------------------------- 1 | Company Job Description 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Company Job Description service provides a list of job descriptions and education details for jobs that a company has 15 | previously posted. 16 | 17 | Company Job Description is available at `/core/company/jobdescriptions`. 18 | 19 | 20 | ## Request Structure 21 | 22 | Requests consist of: 23 | 24 | | | | 25 | |--------------------|--------| 26 | | `company_id` | string | 27 | | `carotene_id` | string | 28 | | `carotene_version` | string | 29 | | `city` | string | 30 | | `state` | string | 31 | | `country` | string | 32 | 33 | Example cURL request: 34 | 35 | ``` 36 | curl -X POST \ 37 | https://api.careerbuilder.com/core/company/jobdescriptions \ 38 | -H 'Accept: application/json;version=1.0' \ 39 | -H 'Authorization: ' \ 40 | -H 'Content-Type: application/json' \ 41 | -d '{ 42 | "company_id": "NC5aea2e1d-383f-4659-82d5-bceaf48918c8", 43 | "carotene_id": "15.5", 44 | "carotene_version": "caroteneV3", 45 | "city": "Quantico", 46 | "state": "VA", 47 | "country": "US" 48 | }' 49 | ``` 50 | 51 | Note that currently only Carotene v3 is supported. See the documentation for [Job Title service](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/JobTitle.md) 52 | for more information about carotene classification and carotene IDs. 53 | 54 | 55 | ## Response Structure 56 | The response consists of a list of `job_descriptions` where each item contains a `description`, an 57 | `id`, and an `education` object containing a `degree` and a list of `majors`, which have a `major` and 58 | a `confidence`. 59 | 60 | Example response body: 61 | 62 | ```json 63 | { 64 | "data": { 65 | "job_descriptions": [ 66 | { 67 | "id": "617aa090-6d42-3729-9df4-0b803567fd52", 68 | "description": "Maintain backup/disaster recovery solutions" 69 | }, 70 | { 71 | "id": "a255879d-21f9-33e9-b2e4-d7cfc9a40787", 72 | "description": "Provide user support and guidance" 73 | } 74 | ], 75 | "education": { 76 | "degree": "Bachelor's Degree", 77 | "majors": [ 78 | { 79 | "major": "Computer Science", 80 | "confidence": 0.41 81 | }, 82 | { 83 | "major": "Business Administration", 84 | "confidence": 0.199 85 | } 86 | ] 87 | } 88 | } 89 | } 90 | ``` 91 | 92 | ## Versioning 93 | The current version of the service is 1.0. 94 | 95 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 96 | 97 | Our general versioning strategy is available [here](/Versioning.md). 98 | -------------------------------------------------------------------------------- /CompanyAddress.md: -------------------------------------------------------------------------------- 1 | Company Address 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Company Address Service takes a request containing a company id and other company details as described in the below request structure and returns a response containing company address and normalized name of master company. The company address will be that of the branch we provide in the request. If branch is not provided then will try to get match against the given location parameters. If multiple results are found, we will return empty response. CompanyAddress is available at 15 | ` https://api.careerbuilder.com/core/geography/companyaddress`. 16 | 17 | 18 | ## Request Structure 19 | Request consist of: 20 | 21 | | Field Name | Type | Required | 22 | |-------------------|--------|----------| 23 | |`company_id` | string | True | 24 | |`country` | string | False | 25 | |`state` | string | False | 26 | |`city` | string | False | 27 | |`branch` | string | False | 28 | |`postal_code` | string | False | 29 | 30 | Example cURL request: 31 | 32 | ``` 33 | curl -X POST \ 34 | https://api.careerbuilder.com/core/geography/companyaddress \ 35 | -H 'Accept: application/json;version=1.0' \ 36 | -H 'Authorization: ' \ 37 | -H 'Content-Type: application/json' \ 38 | -d '{ 39 | "postal_code": "53211", 40 | "company_id": "NC496cd8bb-93bf-4fe1-b9fc-4c966f4f95e5", 41 | "city": "Milwaukee", 42 | "state": "WI", 43 | "branch": "10th Street Comprehensive Treatment Center", 44 | "country": "US" 45 | }' 46 | ``` 47 | 48 | 49 | 50 | ## Response Structure 51 | All responses with an HTTP status of 200 will consist of a JSON object with a top-level "data" node. The response consists of company address and other location parameters like country, state, city, postal code, latitude, longitude and branch codes as show in the below sample response. The latitude and longitude are optional fields. 52 | ### Sample Response 53 | ```json 54 | { 55 | "data": { 56 | "id": "NC496cd8bb-93bf-4fe1-b9fc-4c966f4f95e5", 57 | "normalized_name": "Acadia Healthcare Company, Inc.", 58 | "branch_name": "10th Street Comprehensive Treatment Center", 59 | "branch_codes": [ 60 | "10th Street Comprehensive Treatment Center" 61 | ], 62 | "address": "4800 S 10th St", 63 | "city": "Milwaukee", 64 | "state": "WI", 65 | "postal_code": "53211", 66 | "country": "US", 67 | "latitude" : 33.88, 68 | "longitude" : -88.3 69 | } 70 | } 71 | ``` 72 | 73 | 74 | ## Versioning 75 | The current version of the service is 1.0. 76 | 77 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 78 | 79 | Our general versioning strategy is available [here](/Versioning.md). 80 | -------------------------------------------------------------------------------- /ApplicantQualityScore.md: -------------------------------------------------------------------------------- 1 | Applicant Quality Score Service 2 | ==================== 3 | 4 | Table of Contents 5 | _____________ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | Summary 13 | ----------- 14 | Applicant Quality Score Service is a service helps JobSeekers check how well their profiles match job requirements before applying. 15 | 16 | For each job you add, we provide a relevance score: 17 | 18 | * 1 - Not Relevant 19 | * 2 - Low Relevant 20 | * 3 - Relevant 21 | * 4 - High Relevant 22 | 23 | The Applicant Quality Score Service is available at `/core/application-quality-score`. 24 | 25 | Request Structure 26 | ----------- 27 | 28 | Requests consist of: 29 | 30 | | Parameter | Require/Optional | Type | Description | 31 | |:----------------------|:-----------------|:----------------|:------------------------------------------| 32 | | `email ` | Yes | String | JobSeeker Email | 33 | | `job_did ` | yes | Array of String | An array of job DIDs for the application. | 34 | 35 | 36 | Example cURL request : 37 | 38 | ``` 39 | curl -X POST \ 40 | https://api.careerbuilder.com/core/application-quality-score \ 41 | -H 'Accept: application/json;version=1.0' \ 42 | -H 'Authorization: ' \ 43 | -H 'Content-Type: application/json' \ 44 | -d '{ 45 | "email":"email@example.com", 46 | "job_did": ["J8B2606V22T551FGNWF","J8B36Z60T1523M7FNNN","J7X1RQ68Q8Z3QX327WK","J8D8FN7111Q70X662Z1","JHN0YB6BKFL70JB7LB0","JD67L36K6XGYLD9LBGD","JD825Z6WS1GH0QP7KDC"] 47 | }' 48 | ``` 49 | 50 | Response Structure 51 | ----------- 52 | Upon a successful execution, the response will have a status code of 200 and a JSON content with the following structure: 53 | 54 | job_did (string): The job ID for which the quality score is calculated. 55 | relevant (number): Indicates the relevance of the applicant to the job. 56 | 57 | 58 | 59 | ```json 60 | { 61 | "data": [ 62 | { 63 | "job_did": "JD825Z6WS1GH0QP7KDC", 64 | "relevant": 3, 65 | "score": 0.69072 66 | }, 67 | { 68 | "job_did": "J8D8FN7111Q70X662Z1", 69 | "relevant": 3, 70 | "score": 0.62685 71 | }, 72 | { 73 | "job_did": "J7X1RQ68Q8Z3QX327WK", 74 | "relevant": 3, 75 | "score": 0.66062 76 | }, 77 | { 78 | "job_did": "JHN0YB6BKFL70JB7LB0", 79 | "relevant": 3, 80 | "score": 0.62271 81 | }, 82 | { 83 | "job_did": "J8B2606V22T551FGNWF", 84 | "relevant": 3, 85 | "score": 0.6737 86 | }, 87 | { 88 | "job_did": "J8B36Z60T1523M7FNNN", 89 | "relevant": 3, 90 | "score": 0.66685 91 | }, 92 | { 93 | "job_did": "JD67L36K6XGYLD9LBGD", 94 | "relevant": 3, 95 | "score": 0.72922 96 | } 97 | ] 98 | } 99 | ``` 100 | Versioning 101 | ----------- 102 | The response from the Optimizer Service is versioned with the current version being 1.0. 103 | 104 | Our general versioning strategy is available [here](/Versioning.md). 105 | -------------------------------------------------------------------------------- /Optimizer.md: -------------------------------------------------------------------------------- 1 | Optimizer Service 2 | ==================== 3 | 4 | Table of Contents 5 | _____________ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | Summary 13 | ----------- 14 | Optimizer service is a tool that helps customers find the best application for their needs and budget. It does this by taking into account a variety of factors, including the customer's budget and the price of the application. 15 | 16 | The service will then present the customer with a list of expected applications. 17 | 18 | This information can help the customer make an informed decision about which "solution" to choose. 19 | 20 | The Optimizer service is available at `/core/optimizer`. 21 | 22 | Request Structure 23 | ----------- 24 | 25 | Requests consist of: 26 | 27 | | Parameter | Require/Optional | Type | Description | 28 | |:----------------------|:-----------------|:--------|:----------------------------------------| 29 | | `budget` | Yes | float | Total Customer budget | 30 | | `obj_type` | yes | string | Objective to optimize "Budget" or "EOI" | 31 | | `dynamic_upper_bound` | yes | boolean | ? | 32 | | `constraints` | Yes | string | Array of constraints | 33 | 34 | Constraints example : 35 | 36 | | Parameter | Require/Optional | Type | Description | 37 | |:-------------------|:-----------------|:--------|:--------------------------------| 38 | | `id` | Yes | string | JobDID | 39 | | `price` | yes | float | Price of the application ? | 40 | | `cost` | yes | float | Cost of the application ? | 41 | | `min_applications` | yes | boolean | Minimum applications required ? | 42 | | `max_applications` | Optional | string | Maximum applications required ? | 43 | 44 | Example cURL request : 45 | 46 | ``` 47 | curl -X POST \ 48 | https://api.careerbuilder.com/core/optimizer \ 49 | -H 'Accept: application/json;version=1.0' \ 50 | -H 'Authorization: ' \ 51 | -H 'Content-Type: application/json' \ 52 | -d '{ 53 | "budget": 2000, 54 | "obj_type": "budget", 55 | "dynamic_upper_bound": "false", 56 | "constraints": [ 57 | { 58 | "id": "Job1", 59 | "price": 40, 60 | "cost": 20, 61 | "min_applications":12 62 | }, 63 | { 64 | "id": "Job2", 65 | "price": 30, 66 | "cost": 20, 67 | "min_applications": 6 68 | } 69 | ] 70 | }' 71 | ``` 72 | 73 | Response Structure 74 | ----------- 75 | The returned response is a status and optimized solutions for expected jobs. 76 | You will have in each solution expected application 77 | 78 | ```json 79 | { 80 | "data": { 81 | "status": "Optimal", 82 | "solutions": [ 83 | { 84 | "id": "Job1", 85 | "applications": 14 86 | }, 87 | { 88 | "id": "Job2", 89 | "applications": 48 90 | } 91 | ] 92 | } 93 | } 94 | ``` 95 | Versioning 96 | ----------- 97 | The response from the Optimizer Service is versioned with the current version being 1.0. 98 | 99 | Our general versioning strategy is available [here](/Versioning.md). 100 | -------------------------------------------------------------------------------- /CaroteneSkills.md: -------------------------------------------------------------------------------- 1 | Carotene Skills 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Carotene Skills service provides skills for a given carotene id. CaroteneSkills is available at 15 | `/core/caroteneskills`. 16 | 17 | 18 | ## Request Structure 19 | Requests consist of: 20 | 21 | | Field Name | Type | 22 | |-------------------|--------| 23 | |`carotene_id` | string | 24 | |`carotene_version` | string | 25 | 26 | Example cURL request: 27 | 28 | ``` 29 | curl -X POST \ 30 | https://api.careerbuilder.com/core/caroteneskills \ 31 | -H 'Accept: application/json;version=1.0' \ 32 | -H 'Authorization: ' \ 33 | -H 'Content-Type: application/json' \ 34 | -d '{ 35 | "carotene_id": "11.0", 36 | "carotene_version": "CAROTENEV3" 37 | }' 38 | ``` 39 | 40 | Currently only Carotene v3 is supported. See the documentation for [Job Title service](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/JobTitle.md) 41 | for more information about carotene classification and carotene IDs. 42 | 43 | ## Response Structure 44 | Response consist of a `carotene_id`, `carotene_title`, and list of `skills` for the requested 45 | `carotene_id`. Each item in the `skills` list contains `term`, `id`, and `description` 46 | strings, as well as a list of links to relevant videos. 47 | 48 | ```json 49 | { 50 | "data": { 51 | "skills": [ 52 | { 53 | "term": "manage sale team", 54 | "id": "KS123X777H5WFNXQ6BPM", 55 | "description": "Sales are activities related to selling or the number of goods or services sold in a given time period. The seller or the provider of the goods or services complete a sale in response to an acquisition, appropriation, requisition or a direct interaction with the buyer at the point of sale.", 56 | "videos": [ 57 | { 58 | "url": "https://www.youtube.com/watch?v=Qnd8j8rxEB0", 59 | "video_title": "Tips to Build and Manage an Excellent Sales Team" 60 | }, 61 | { 62 | "url": "https://www.youtube.com/watch?v=CZicBw_mShE", 63 | "video_title": "HOW TO INSPIRE YOUR SALES TEAM (SALES AND LEADERSHIP TRAINING INDIANAPOLIS)" 64 | } 65 | ] 66 | }, 67 | { 68 | "term": "business development", 69 | "id": "KS1212B6QR5SK1LSD4S4", 70 | "description": "Business development entails tasks and processes to develop and implement growth opportunities within and between organizations. It is a subset of the fields of business, commerce and organizational theory.", 71 | "videos": [ 72 | { 73 | "url": "https://www.youtube.com/watch?v=i5Xwy-XBVgk", 74 | "video_title": "The 10 Keys to Business Development" 75 | }, 76 | { 77 | "url": "https://www.youtube.com/watch?v=OB2t8UvXMWU", 78 | "video_title": "Creating a Sales and Business Development Strategy - Entrepreneurship 101 2009/10" 79 | } 80 | ] 81 | } 82 | ] 83 | } 84 | } 85 | ``` 86 | 87 | 88 | ## Versioning 89 | The current version of the service is 1.0. 90 | 91 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 92 | 93 | Our general versioning strategy is available [here](/Versioning.md). 94 | -------------------------------------------------------------------------------- /Versioning.md: -------------------------------------------------------------------------------- 1 | Data Science API Versioning 2 | ================ 3 | 4 | Contents 5 | ---------- 6 | - [Overview](#overview) 7 | - [Contract Versioning](#contract-versioning) 8 | - [Data Versioning](#data-versioning) 9 | - [Errors and HTTP Status Codes](#errors-and-http-status-codes) 10 | - [Alpha and Beta Versions](#alpha-and-beta-versions) 11 | - [Sunsetting Versions](#sunsetting-versions) 12 | - [Version Specification](#version-specification) 13 | 14 | 15 | # Overview 16 | This document attempts to explain the Data Science approach to versioning our APIs and data. This is intended as a general document and anything can be superceded by specific API documentation. Each API has a Version section in its documentation that lists any variances with this document. In general, large changes result in a new major version and small changes result in a new minor version. 17 | 18 | # Contract Versioning 19 | Our APIs contracts are versioned. No breaking changes (field removal or renaming) will be made to either the input or the response without versioning. Field additions are not versioned. Ordering of fields and items within lists is unversioned and may change without warning unless noted in the API's documentation. Small changes will be given minor versions; large changes will be given major versions. Even small changes may be breaking changes (such as renaming a field). 20 | 21 | # Data Versioning 22 | The data returned from our APIs may or may not be versioned. This will be indicated in each API's documentation. If an API's data is versioned it means that the same input and version will always yield the same output. If an API's data is not versioned there will be a discussion in the API documentation about what can change and the expected reasons and rate of change. In APIs that have a set taxonomy for outputs, all versions' taxonomies will be listed in the documentation. Any additions or deletions from a set taxonomy will result in a new major version. Other changes to the output such as reranking or renaming may result in a minor version. Note that a data versioned API may add new fields to the output or new optional inputs without a new version. Fixing a deterministic bug in a data versioned API will be done in a new version. 23 | 24 | # Errors and HTTP Status Codes 25 | The contract of how errors are returned is versioned. Several APIs return errors in non-standard ways; we are working towards standardizing them which will result in new versions. The HTTP Status Codes and contents of errors such as messages and error numbers is unversioned and may change without notice. 26 | 27 | # Alpha and Beta Versions 28 | Occasionally we may release new versions of APIs in an Alpha or Beta state. Availability of Alpha or Beta versions may not be widely communicated; we may let a single customer test an API. Alpha and Beta APIs may be changed without notification, including breaking changes, and consumers should code appropriately. In addition, Alpha APIs are not yet ready for production scale traffic and should not be hit at scale. 29 | 30 | # Sunsetting Versions 31 | Old versions of APIs will be sunset as appropriate. All consumers of APIs are committing to do the work necessary to move from sunset APIs to newer versions. Any API sunset dates will be communicated with all users of the API. Our goal is to announce sunset dates at least 6 weeks before the sunset date to allow consumers time to react, though tighter timelines may be required in exceptional situations. For data versioned APIs our intention is to support two major versions at all times, and to announce the sunset of the third newest major version upon the release of the newest major version. For example, when Version 5.0 is released, Versions 3.x sunset date is announced. 32 | 33 | # Version Specification 34 | Per CB standard, version is passed in through the Accept header, and if no version is specified the newest version is used. Defaulting to the latest version creates the possibility of unexpected failure in your application due to breaking changes resulting from version upgrades. API consumers are strongly encouraged to specify a version when interacting with APIs. 35 | -------------------------------------------------------------------------------- /EstimatedApplications.md: -------------------------------------------------------------------------------- 1 | Estimated Applications Service 2 | ==================== 3 | 4 | Table of Contents 5 | _____________ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | Summary 13 | ----------- 14 | The Estimated Applications service returns applications numbers expected per chanel for a onet code and, optionally, a location (admin_area and locality). 15 | 16 | Applications info can be requested in either daily,weekly,monthly numbers. 17 | 18 | e.g.: How much does applicant for `Customer service representative` may I get per `month` in `Chicago`? 19 | 20 | The estimated applications service is available at `/core/estimated_applications`. 21 | 22 | Request Structure 23 | ----------- 24 | 25 | Requests consist of: 26 | 27 | | Parameter | Require/Optional | Type | Description | 28 | |:-----------------|:-------|:-------|:----------------------------------------------------------------------------------------------------------------------------------------------| 29 | | `onet_code` | Yes | string | A unique id representing a onet_code job title classification https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/oNet17.md | 30 | | `locality` | Optional | string | An existing city. | 31 | | `admin_area_1` | Optional | string | A valid state. | 32 | | `period` | Yes | string | Possible values are "day", "week", "month". | 33 | 34 | 35 | Example cURL request : 36 | 37 | ``` 38 | curl -X POST \ 39 | https://api.careerbuilder.com/core/estimated_applications \ 40 | -H 'Accept: application/json;version=1.0' \ 41 | -H 'Authorization: ' \ 42 | -H 'Content-Type: application/json' \ 43 | -d '{ 44 | "locality": "atlanta", 45 | "admin_area_1": "ga", 46 | "onet_code": "19-1031.03", 47 | "period": "day" 48 | }' 49 | ``` 50 | 51 | Response Structure 52 | ----------- 53 | The returned response is an expected array with application per type and channel : 54 | 55 | We bring back response for each type of jobs : 56 | * Internal 57 | * External 58 | * Programmatic 59 | 60 | For each type we provide expect number per channel. 61 | If we do not have data, null is returned. 62 | List of channels : 63 | * ajb 64 | * djr 65 | * email_aa 66 | * job_alert 67 | * post_apply 68 | * jdp 69 | * newsletter 70 | * email_after_apply 71 | * jrp 72 | * jobrecpage 73 | * colab 74 | * organic_search 75 | * talent_network 76 | * company_detail_pages 77 | * sponsored_jobs 78 | * ret 79 | * other 80 | 81 | daily response eg: 82 | ```json 83 | { 84 | "data": { 85 | "internal": { 86 | "ajb": null, 87 | "djr": 2, 88 | "email_aa": 3, 89 | "job_alert": 4, 90 | "post_apply": 5, 91 | "jdp": 6, 92 | "newsletter": 26, 93 | "email_after_apply": 27, 94 | "jrp": 28, 95 | "jobrecpage": 29, 96 | "colab": 30, 97 | "organic_search": 31, 98 | "talent_network": 21, 99 | "company_detail_pages": 33, 100 | "sponsored_jobs": 34, 101 | "ret": 35, 102 | "other": 36 103 | }, 104 | "external": { 105 | "ajb": 8, 106 | "djr": 9, 107 | "email_aa": 1, 108 | "job_alert": 2, 109 | "post_apply": 3, 110 | "jdp": 4, 111 | "newsletter": 46, 112 | "email_after_apply": 47, 113 | "jrp": 48, 114 | "jobrecpage": 49, 115 | "colab": 50, 116 | "organic_search": 51, 117 | "talent_network": 52, 118 | "company_detail_pages": 53, 119 | "sponsored_jobs": 54, 120 | "ret": 55, 121 | "other": 56 122 | }, 123 | "programmatic": { 124 | "ajb": 6, 125 | "djr": 7, 126 | "email_aa": 8, 127 | "job_alert": 9, 128 | "post_apply": 1, 129 | "jdp": 2, 130 | "newsletter": 46, 131 | "email_after_apply": 47, 132 | "jrp": 48, 133 | "jobrecpage": 49, 134 | "colab": 50, 135 | "organic_search": 51, 136 | "talent_network": 52, 137 | "company_detail_pages": 53, 138 | "sponsored_jobs": 54, 139 | "ret": 55, 140 | "other": 56 141 | } 142 | } 143 | } 144 | ``` 145 | Versioning 146 | ----------- 147 | The response from the Estimated Application Service is versioned with the current version being 1.0. 148 | 149 | Our general versioning strategy is available [here](/Versioning.md). 150 | -------------------------------------------------------------------------------- /SemanticOverrides.md: -------------------------------------------------------------------------------- 1 | Semantic Overrides API 2 | =================== 3 | Allows users and curators to add enrichments, remove enrichments, and make enrichments selected or unselected in real time for 4 | any canonical term and any taxonomy supported by Semantic 1.0 5 | 6 | # Global Overrides 7 | Global overrides are administrated by authorized curators via the Overrides UI tool. The tool is located at 8 | http://www.careerbuilder.com/nlUtils/SemanticOverridesTool/SemanticOverride.html?g=true 9 | The tool will only work for those on an approved list. For questions about gaining access, send an email to 10 | DataScienceApplicationDevelopment@careerbuilder.com 11 | 12 | # User Overrides 13 | User overrides are only applied to Semantic Search requests with a corresponding user_id, 14 | allowing personalization of Semantic Search results. User overrides have priority over global overrides, and are applied to 15 | any extracted keyword for which an override exists. 16 | 17 | ## User Overrides Request 18 | 19 | User overrides are added and deleted using a RESTful interface. 20 | 21 | ### HTTP method PUT 22 | 23 | Adds or updates an override for the specified user_id, term, language, taxonomy, and enrichment combination. 24 | Since this endpoint modifies override state, it is restricted to certain OAuth client ids. For questions about access, send an email to 25 | DataScienceApplicationDevelopment@careerbuilder.com 26 | 27 | Path parameter structure: https://api.careerbuilder.com/core/SemanticOverrides/user/{user_id}/{term}/{language}/{taxonomy}/{enrichment} 28 | 29 | Parameters (URL-encoded path parameters): 30 | - user_id (required): A globally unique id to associate with the override request. 31 | Note that if your id collides with an existing id, the the existing id will be modified - we recommend using globally unique identifiers. 32 | - term (required): the extracted keyword to which to apply the override. Note that special characters should be url-encoded. 33 | Note that the Matrix OAuth framework requires forward slashes in path parameters to be double-encoded (%252F) 34 | - language (required): The language to which the override applies. A two letter language code followed by underscore, followed by two letter country code. Required to use personalized overrides. Currently, allowed values are en_us, en_gb, fr_fr, de_de, and nl_nl. 35 | - taxonomy (required): The Taxonomy to which the override applies. Current valid taxonomies correspond to taxonomies returned by the Semantic Search API and are listed below. 36 | - enrichment (required): The enrichment to override. Whether to supply the enrichment id or name depends on the taxonomy, 37 | as outlined below. Enrichment ids are validated against the CB Taxonomy, while names can by any string. 38 | 39 | | Taxonomy | Supply Enrichment Id or Name? | 40 | |----------|--------------| 41 | |RelatedSearchTermsV1 | Name | 42 | |RelatedSearchTermsRecruiterV1 | Name | 43 | |RelatedSearchTermsJobseekerV1 | Name| 44 | |TextKernelRelatedSearchTerms | Name | 45 | |RawJobTitlesJobSeekerV1 | Name | 46 | |RawJobTitlesRecruiterV1 | Name | 47 | |CustomKeywords| Name | 48 | |ONet17| Id | 49 | |CaroteneV3 | Id | 50 | |SkillsV4 | Id | 51 | 52 | Parameters (Body parameters): 53 | - returned (required): boolean, defaults to false. Whether to return this enrichment, under this taxonomy, in queries containing this term and for this language and user_id. 54 | - selected (required): nullable boolean, defaults to null. Sets state of the "selected" flag in the Semantic Search response for this enrichment, under this taxonomy, in queries containing this term and for this language and user_id. 55 | 56 | Example Request 57 | ``` 58 | HTTP PUT 59 | https://api.careerbuilder.com/core/SemanticOverrides/user/U123456789/java+developer/en_us/CaroteneV3/15.2/ 60 | Body: 61 | returned=true&selected=true 62 | ``` 63 | 64 | The response will include no data unless an error occurred, in which case the response will be in CB API standard format. 65 | 66 | ### HTTP Method DELETE 67 | 68 | Removes an override for the specified user_id, term, language, taxonomy, and enrichment combination. The Semantic Search API will return its default behavior for this user_id/language before this override was added. 69 | Since this endpoint modifies override state, it is restricted to certain OAuth client ids. For questions about access, send an email to 70 | DataScienceApplicationDevelopment@careerbuilder.com 71 | 72 | Path parameter structure: https://api.careerbuilder.com/core/SemanticOverrides/user/{user_id}/{term}/{language}/{taxonomy}/{enrichment} 73 | 74 | Parameters: 75 | 76 | Identical to PUT parameters, except that body parameters are ignored. 77 | 78 | Example Request 79 | ``` 80 | HTTP DELETE 81 | https://api.careerbuilder.com/core/SemanticOverrides/user/U123456789/java+developer/en_us/CaroteneV3/15.2/ 82 | ``` 83 | The response will include no data unless an error occurred, in which case the response will be in CB API standard format. 84 | 85 | # Versioning information 86 | 87 | Overrides are stored for versions of taxonomies and applied only to the same Taxonomy/version in the Semantic Search response. 88 | For example, an override for Carotene v3 will not apply to a hypothetical future Semantic Search version which returns Carotene v4. 89 | The API itself is currently unversioned. 90 | 91 | -------------------------------------------------------------------------------- /SalaryService.md: -------------------------------------------------------------------------------- 1 | Salary Service 2 | ==================== 3 | 4 | Table of Contents 5 | _____________ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | Summary 13 | ----------- 14 | The Salary service returns salary info for a carotene id and, optionally, a postal or a CBSA code. 15 | Salary info can be requested in either hourly or yearly amounts. 16 | 17 | e.g.: How much does a `Customer service representative` make per `year` in `Chicago`? 18 | 19 | The Salary service is available at `/core/salary`. 20 | 21 | OG data is now supported, you can pass hostite and country to query only on OG data. 22 | 23 | Request Structure 24 | ----------- 25 | 26 | Requests consist of: 27 | 28 | | Parameter | Require/Optional | Type | Description | 29 | |:----------|:-------|:-------|:-------| 30 | |`carotene_id`| Yes | string | A unique id representing a carotene job title classification https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/JobTitle.md#taxonomies| 31 | |`cbsa_code` | Optional | string | Unique Identifiers for US metropolitan statistical areas. | 32 | |`postal_code` | Optional | string | A postal code.| 33 | |`salary_period` | Yes | string | Possible values are "Year", "Hour". | 34 | |`country` | Yes | string | An ISO-3166 country code.| 35 | |`hostsite` | Optional | string | A valid CareerBuilder hostsite.("US", "OG" are supported for now). Defaulted to US if not provided | 36 | 37 | Example cURL request with cbsa_code: 38 | 39 | ``` 40 | curl -X POST \ 41 | https://api.careerbuilder.com/core/salary \ 42 | -H 'Accept: application/json;version=1.0' \ 43 | -H 'Authorization: ' \ 44 | -H 'Content-Type: application/json' \ 45 | -d '{ 46 | "carotene_id": "43.1", 47 | "cbsa_code": "26420", 48 | "salary_period": "year", 49 | "country": "US" 50 | }' 51 | ``` 52 | 53 | Example cURL request with postal_code: 54 | 55 | ``` 56 | curl -X POST \ 57 | https://api.careerbuilder.com/core/salary \ 58 | -H 'Accept: application/json;version=1.0' \ 59 | -H 'Authorization: ' \ 60 | -H 'Content-Type: application/json' \ 61 | -d '{ 62 | "carotene_id": "43.1", 63 | "postal_code": "77494", 64 | "salary_period": "year", 65 | "country": "US" 66 | }' 67 | ``` 68 | 69 | Example cURL request nationwide: 70 | 71 | ``` 72 | curl -X POST \ 73 | https://api.careerbuilder.com/core/salary \ 74 | -H 'Accept: application/json;version=1.0' \ 75 | -H 'Authorization: ' \ 76 | -H 'Content-Type: application/json' \ 77 | -d '{ 78 | "carotene_id": "43.1", 79 | "salary_period": "year", 80 | "country": "US" 81 | }' 82 | ``` 83 | 84 | Example cURL request with hostsite request: 85 | 86 | ``` 87 | curl -X POST \ 88 | https://api.careerbuilder.com/core/salary \ 89 | -H 'Accept: application/json;version=1.0' \ 90 | -H 'Authorization: ' \ 91 | -H 'Content-Type: application/json' \ 92 | -d '{ 93 | "carotene_id": "43.1", 94 | "salary_period": "year", 95 | "country": "UK" 96 | "hostsite": "OG" 97 | }' 98 | ``` 99 | 100 | Response Structure 101 | ----------- 102 | The returned response is a salary information of a given carotene id and location 103 | consist of: 104 | 105 | | Parameter | Type | Description | 106 | |:----------|:-------|:-------| 107 | |`currency` | string | An ISO 4217 currency code.| 108 | |`percentile_10` | string | 10th percentile wage of the requested `salary_period`. | 109 | |`percentile_90` | string | 90th percentile wage of the requested `salary_period`. | 110 | |`percentile_25` | string | 25th percentile wage of the requested `salary_period`. | 111 | |`percentile_75` | string | 75th percentile wage of the requested `salary_period`. | 112 | |`median` | string | median wage of the requested `salary_period`. | 113 | |`mean` | string | mean wage of the requested `salary_period`. | 114 | |`employment_per_thousand_jobs` | string | An Employment rate per 1000 jobs | 115 | |`wage_percent_relative_standard_error` | string | - | 116 | |`salary_period` | string | Possible values are `YEAR`, `HOUR` based on the requested`salary_period`.| 117 | 118 | Yearly Response: 119 | ```json 120 | { 121 | "data": { 122 | "currency": "USD", 123 | "percentile_10": 21870.0, 124 | "percentile_90": 59100.0, 125 | "percentile_25": 30660.0, 126 | "percentile_75": 48340.0, 127 | "median": 38500.0, 128 | "mean": 39690.0, 129 | "employment_per_thousand_jobs": 12.311, 130 | "wage_percent_relative_standard_error": 1.2, 131 | "salary_period": "YEAR" 132 | } 133 | } 134 | ``` 135 | Hourly Response: 136 | ```json 137 | { 138 | "data": { 139 | "currency": "USD", 140 | "percentile_10": 10.52, 141 | "percentile_90": 29.049999999999997, 142 | "percentile_25": 14.74, 143 | "percentile_75": 23.24, 144 | "median": 18.51, 145 | "mean": 19.08, 146 | "employment_per_thousand_jobs": 12.311, 147 | "wage_percent_relative_standard_error": 1.2, 148 | "salary_period": "HOUR" 149 | } 150 | } 151 | ``` 152 | Versioning 153 | ----------- 154 | The response from the Salary Service is versioned with the current version being 1.0. 155 | 156 | Our general versioning strategy is available [here](/Versioning.md). 157 | -------------------------------------------------------------------------------- /SemanticAutocomplete.md: -------------------------------------------------------------------------------- 1 | Semantic Autocomplete V2 2 | ======================== 3 | 4 | #### Table of Contents 5 | 6 | - [Summary](#summary) 7 | - [Request](#request) 8 | - [Response](#response) 9 | - [Example](#example) 10 | - [Versioning](#versioning) 11 | 12 | 13 | ## Summary 14 | Semantic Autocomplete is a service which provides textual autocomplete for search terms relating to DSAD's Semantic Search API. Version 2 of the Semantic Autocomplete service is a complete rewrite of the original service and makes use of the latest FSTs provided to DSAD from Textkernel. Textkernel refines FSTs throughout the year and updates happen every few months. With the exception of some removed fields from the response, this version of the service functions exactly like V1. 15 | 16 | For ease of use DSAD auto-generates and publishes Java and C# SDKs for all of our services using swagger. For documentation on usage please see our SDK repo [here](https://github.com/cbdr/dsad-sdks). All sdks are published to [cbdatascience jfrog artifactory](https://cbdatascience.jfrog.io/cbdatascience/webapp/#/home) and located in *ext-release-local/com/careerbuilder/datascience/sdk/*. Jfrog is managed by the CloudOps team, for permissions accessing artifacts please reach out to CloudOpsSupport@careerbuilder.com. 17 | 18 | ## Request 19 | As with all DSAD services, Semantic Autocomplete accepts requests sent as either HTTP GET or HTTP POST. Access to semantic autocomplete is made available at: 20 | https://www.api.careerbuilder.com/core/semanticsearch/autocomplete 21 | 22 | This service requires Careerbuilder Oauth 2.0 client credentials. For more information please see our ReadMe [here](/Readme.md#access). 23 | 24 | #### Parameters: 25 | | Parameter | Require/Optional | Type | Description | 26 | |-----------|------------------|------|-------------| 27 | | query | Required | String | The `query` value to autocomplete. 28 | | limit | Optional | Integer | The number of results expected to return. 29 | 30 | **The limit field cannot exceed a size of 100 and defaults to 10 without the value present.** 31 | 32 | The current version of the service is `2.0`. Version must be specified in the ```Accept``` header. 33 | 34 | Example: ```Accept: application/json;version=2.0``` 35 | 36 | ## Response 37 | The response data is broken up into two parts: the original `query` and the list of suggestions returned from Solr. The first `suggestion` will always be identified with the `type` *free_text* and the associated `value` is that of the highest `popularity` of the returned results. 38 | 39 | ### Data 40 | | Field | Type | Description | 41 | |-------|------|-------------| 42 | | query | String | Original query sent to Solr. 43 | | suggests | Suggestion[] | A json array of Suggestions broken up by type. 44 | 45 | ### Suggestion 46 | 47 | | Field | Type | Description | 48 | |-------|------|-------------| 49 | | type | String | The type or cannonical form of the suggestion. Possible returned values are: *keyword, job_title, job_level, occupation, skill, school, company, location, freetext* 50 | | values | value[] | A json array of values associated with the type. 51 | 52 | 53 | ### Value 54 | A value object represents the surface forms associated with the type(cannonical) suggested for autocomplete. E.g., provided "e" as a query, under the `type` *job_title* you would see `names` like engineer, executive, sales executive, etc. 55 | 56 | | Field | Type | Description | 57 | |-------|------|-------------| 58 | | name | String | A name associated with the type classification. 59 | | popularity | Integer | An integer value indicating how often the term appears in resumes or job postings. 60 | 61 | #### Notable Changes in V2 62 | Version 1 of the service maintained a timing object as part of the data field. This is no longer returned in version 2. 63 | ``` 64 | { 65 | "data" : { 66 | ... 67 | "timing": { 68 | "time_received": "2018-10-29T17:35:23.724276-04:00", 69 | "time_elapsed_seconds": 0.031250599999999996 70 | } 71 | } 72 | 73 | } 74 | ``` 75 | 76 | ### Example 77 | Provided the Request: https://www.api.careerbuilder.com/core/semanticsearch/autocomplete?query="e"&limit=5 78 | 79 | ``` 80 | { 81 | "data": { 82 | "query": "e", 83 | "suggests": [ 84 | { 85 | "type": "freetext", 86 | "values": [ 87 | { 88 | "name": "engineer", 89 | "popularity": 345628 90 | } 91 | ] 92 | }, 93 | { 94 | "type": "skill", 95 | "values": [ 96 | { 97 | "name": "E-Commerce", 98 | "popularity": 80804 99 | } 100 | ] 101 | }, 102 | { 103 | "type": "job_title", 104 | "values": [ 105 | { 106 | "name": "engineer", 107 | "popularity": 345628 108 | }, 109 | { 110 | "name": "software engineer", 111 | "popularity": 192082 112 | }, 113 | { 114 | "name": "account executive", 115 | "popularity": 162997 116 | }, 117 | { 118 | "name": "sales executive", 119 | "popularity": 79346 120 | } 121 | ] 122 | } 123 | ] 124 | } 125 | ``` 126 | 127 | ## Versioning 128 | The current version for this service is 2.0. Following the adoption of this version Semantic Autocomplete 1.0 will be retired. For more information on our general versioning strategy please visit our guide to versioning [here](/Versioning.md). -------------------------------------------------------------------------------- /CompanyNormalization.md: -------------------------------------------------------------------------------- 1 | Company Normalization Service 2 | ============= 3 | 4 | The Company Normalization Service accepts HTTP GET or POST requests that specify information about a company, and returns normalized company data including but not limited to: name, location, website, and NAICS data. It is backed by the CompanyDepot classifier developed by the Information Extraction and Retrieval team. 5 | 6 | The service handles two types of requests: search requests and lookup requests. Search requests attempt to resolve an unnormalized query to an entity from the CompanyDepot knowledge base. Lookup requests return the normalized entity corresponding to the provided ID. 7 | _________ 8 | - [Search Requests](#search-requests) 9 | - [Search Responses](#search-responses) 10 | - [Lookup Requests](#lookup-requests) 11 | - [Lookup Responses](#lookup-responses) 12 | - [Versioning](#versioning) 13 | 14 | ## Search Requests 15 | 16 | The following parameters may be used in constructing a request to the service: 17 | 18 | Field | Required | Description 19 | -------------------------- |----------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 20 | ```company_name``` | true | The company name to be normalized. 21 | ```website``` | true | The website of the company to be normalized. *(Note: Either* ```company_name``` *or* ```website``` *must be provided. It is not necessary to provide both.)* 22 | ```country``` | false | The country component of the provided company's location. Two-digit ISO country codes are supported. 23 | ```state``` | false | The state component of the provided company's location. 24 | ```city``` | false | The city component of the provided company's location. 25 | ```max_results``` | false | The maximum number of results to be returned, between 1 and 10 (inclusive). Defaults to 3. 26 | ```use_query_classifier``` | false | Specifies whether to detect specific queries (irrelevant queries or agency queries) and return empty results for such queries. This value defaults to true. In order to turn it off users must provide the param with a value of false. 27 | ```filter_by_country``` | false | With this set to false, the country parameter only biases results and this is traditionally how the service has worked. Setting this value to true will filter results based on country. This param defaults to false. 28 | 29 | \* *Note that company_name and website are each constrained to a maximum length of 400 characters. Requests that contain a company_name or website value exceeding this limit will fail with an HTTP 400 Bad Request status.* 30 | 31 | Example: https://api.careerbuilder.com/core/normalizedcompanies?company_name=careerbuilder&max_results=1 32 | 33 | ## Search Responses 34 | 35 | The response for a search request returns a single `data` node which contains a `normalized_companies` array. These normalized companies are ordered by the confidence score (descending). Each normalized company has a `normalized_name` (string), a `naics_code` *([more info](http://www.census.gov/eos/www/naics/))* (string), a `naics_description` (string), a `duns_number`[1](#f1) (string, and always empty), a `country` (string), a `state` (string), a `city` (string), a `postal_code` (string), a `website` (string), a `company_size` (int), an `id` (string), and a `confidence` (decimal). Confidence scores range from 0.0 to 1.0. A single master company will be returned. 36 | 37 | The master company is the highest division of the requested company. For example a request with the company name "amazon web services" returns "Amazon Web Services LLC" in its normalized_companies list, with a master company of "Amazon.com, Inc." 38 | 39 | The top-level data node will also include a `data_version` field that specifies the current CompanyDepot data version as a string. 40 | 41 | Following is an example JSON response body: 42 | 43 | ```json 44 | { 45 | "data": { 46 | "normalized_companies": [ 47 | { 48 | "confidence": 1, 49 | "id": "NC842f69a0-b621-48f6-b53c-9b3301e9aab7", 50 | "normalized_name": "Careerbuilder, LLC", 51 | "postal_code": "606011014", 52 | "city": "Chicago", 53 | "state": "IL", 54 | "naics_code": "561311", 55 | "country": "US", 56 | "address": "200 N La Salle St # 1100", 57 | "naics_description": "Employment Placement Agencies", 58 | "duns_number": "", // deprecated 59 | "company_size": "42868", 60 | "website": "www.careerbuilder.com" 61 | } 62 | ], 63 | "master_company": { 64 | "confidence": 1, 65 | "id": "NC842f69a0-b621-48f6-b53c-9b3301e9aab7", 66 | "normalized_name": "Careerbuilder, LLC", 67 | "postal_code": "606011014", 68 | "city": "Chicago", 69 | "state": "IL", 70 | "naics_code": "561311", 71 | "country": "US", 72 | "address": "200 N La Salle St # 1100", 73 | "naics_description": "Employment Placement Agencies", 74 | "duns_number": "", // deprecated 75 | "company_size": "42868", 76 | "website": "www.careerbuilder.com" 77 | }, 78 | "data_version": "1.0.4" 79 | } 80 | } 81 | ``` 82 | 83 | ## Lookup Requests 84 | 85 | Lookup requests specify an `id` value. This corresponds to the `id` field associated with normalized companies returned by the service. Other parameters from the [Search Requests](#search-requests) section should not be included in these requests; requests constructed with the ˋidˋ parameter alongside other parameters will result in an HTTP 400 Bad Request error. 86 | 87 | ## Lookup Responses 88 | 89 | Lookup responses are identical to search responses in structure, with the `master_company` node always `null` (i.e. not present in the response body). The `normalized_companies` array will contain a single result matching the provided ID if a match was found, and will be empty otherwise. 90 | 91 | ## Versioning 92 | The response from the Company Normalization Service is versioned with the current version being 1.0. The CompanyDepot data is also versioned, and we will always use the latest. 93 | 94 | Our general versioning strategy is available [here](/Versioning.md). 95 | 96 | 1 The `duns_number` is now deprecated and the string will always return empty. It will be removed from later versions. 97 | -------------------------------------------------------------------------------- /LikelihoodToRespond.md: -------------------------------------------------------------------------------- 1 | Likelihood To Respond Service 2 | ============= 3 | 4 | Contents 5 | 6 | - [Overview](#overview) 7 | - [Request Information](#request-information) 8 | - [Response Information](#response-information) 9 | 10 | # Overview 11 | 12 | The Likelihood To Respond (LTR) service provides data to describe the likelihood that a job seeker will respond positively when contacted regarding a new job opportunity. Data returned by the service is computed ahead of time by the Search Data Science team and is refreshed nightly. 13 | 14 | The LTR service is hosted in the CareerBuilder API routing layer's Staging, US Production, and EU Production environments. The relative path for the service is `/core/classifier/likelihoodtorespond`. 15 | 16 | LTR is available for authorized users only. For questions about gaining access, please send an email to DataScienceApplicationDevelopment@careerbuilder.com. 17 | 18 | # Request Information 19 | 20 | The service responds to three types of requests, described in detail in this section. Requests can be provided as HTTP GETs or HTTP POSTs. POST requests may be sent as either `application/json` or `application/x-www-form-urlencoded` content types. 21 | 22 | **Email lookups**
23 | *e.g. ?email_address=example@demo.com* 24 | 25 | The service may be queried with an `email_address` parameter to retrieve the LTR record for a particular job seeker. No validation is performed on the provided email string. If no matching record exists, an empty list will be returned. 26 | 27 | **Generic threshold queries**
28 | *e.g. ?ltr_threshold=0.05* 29 | 30 | The service may be queried with an `ltr_threshold` decimal parameter to retrieve records for job seekers whose generic LTR score matches or exceeds the provided threshold. The `ltr_threshold` parameter must be between 0.0 and 1.0, inclusive. 31 | 32 | **Carotene-specific threshold queries**
33 | *e.g. ?ltr_threshold=0.05&carotene_id=15.1* 34 | 35 | The service may be queried with an `ltr_threshold` parameter accompanied by a `carotene_id` parameter. The `carotene_id` parameter should be a valid and complete CaroteneV3 ID. (A full list of CaroteneV3 IDs can be obtained via the [Taxonomy Service](/TaxonomyService.md).) No validation is performed on the provided Carotene ID. 36 | 37 | **Pagination**
38 | 39 | Generic and Carotene-specific threshold queries will occasionally yield large numbers of results. A single service response will contain a maximum of 1000 results. Pagination controls are available to enable traversal of large result sets. (Note that result sets are always sorted in descending order of the appropriate LTR score for the request type, and the result set for a specific query will remain consistent within a given upload day.) 40 | 41 | A single page is defined as 1000 results. The first page of results returned for a query is page 0; re-issuing the request with `page=1` will return results 1001 through 2000, and so on. The response will contain fields for `page` (indicating the current page), `total` (indicating the total size of the result set), and `page_size` (indicating the maximum number of results to be included in one page). 42 | 43 | A request specifying an out of bounds `page` value (such as `page=6` for a result set of size 3000) will return zero results. A request specifying `page` as anything other than a nonnegative integer will result in an HTTP 400 Bad Request error. 44 | 45 | Empty requests or invalid requests (such as those specifying both `email_address` and `ltr_threshold`, or specifying an `ltr_threshold` value that is not a decimal in the specified range) will result in an HTTP 400 Bad Request error. 46 | 47 | # Response Information 48 | 49 | The service returns a consistent JSON response structure for all requests, regardless of type. All error responses will be returned in accordance with CB API standards and with a descriptive HTTP 4xx or 5xx status code. All successful responses will return data in the following format: 50 | ``` 51 | { 52 | "data": { 53 | "results": [ 54 | { 55 | "email_address": string, 56 | "popularity": int, 57 | "propensity_to_leave": double, 58 | "likelihood_to_respond": double, 59 | "likelihood_to_respond_by_carotene": { 60 | string: double, 61 | string: double, 62 | string: double 63 | }, 64 | "activity_level": int, 65 | "began_working_signal_date": string 66 | }, 67 | [etc...] 68 | ], 69 | "upload_date": string, 70 | "page_size": int, 71 | "total": int, 72 | "page": int 73 | } 74 | } 75 | ``` 76 | Each response field is defined as follows: 77 | * `data`: The top-level node for successful responses, as specified by CB API standards. 78 | * `results`: An array of LTR records. May be empty. For email lookup requests, contains a maximum of one element. For both types of threshold query requests, contains a maximum of 1000 elements. (The `skip_results` request parameter may be used to obtain results beyond the first 1000 for a query.) 79 | * `email_address`: The job seeker's email address. 80 | * `popularity`: A normalized score between 1 (least popular) and 3 (most popular) that describes the frequency with which recruiters have recently performed actions on this job seeker's profile. This field may be null. 81 | * `likelihood_to_respond`: A score between 0.0 (lowest likelihood) and 1.0 (highest likelihood) indicating how likely the job seeker is to respond positively to contacts regarding new job opportunities. This is an overall score that does not consider specific job titles or classifications. 82 | * `likelihood_to_respond_by_carotene`: A map from carotene IDs to LTR scores. Contains between one and three elements describing the carotene ID(s) for which the job seeker is most likely to respond. 83 | * `activity_level`: A normalized score between 1 (least active) and 5 (most active) describing the job seeker's recent activity level on CareerBuilder sites. 84 | * `began_working_signal_date`: A date string (in `YYYY-MM-DD` format) representing the date at which a signal was received indicating that the job seeker was employed. Note that this only indicates when the job seeker confirmed that they were employed, and does not necessarily correspond to the seeker's hiring date. This field may be null. 85 | * `upload_date`: The date at which the current data set was uploaded. This essentially functions as a version number for data returned by the service. The date will be returned in `YYYY-MM-DD` format. 86 | * `page_size`: An integer indicating the maximum number of results that will be returned in a single page. Currently this number is 1000. 87 | * `total`: An integer indicating the total size of the result set. 88 | * `page`: An integer indicating which page of results was returned. Will be identical to the `page` request parameter if provided; otherwise, this field will contain 0. 89 | -------------------------------------------------------------------------------- /PlaceAutocomplete.md: -------------------------------------------------------------------------------- 1 | Place Autocomplete 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Session Tokens and Usage Example](#session-tokens-and-usage-example) 9 | - [Request Structure](#request-structure) 10 | - [Response Structure](#response-structure) 11 | - [Versioning](#versioning) 12 | 13 | ## Summary 14 | 15 | Place Autocomplete (`/core/geography/place/autocomplete`) is a wrapper service for Google's Place 16 | Autocomplete API, which returns place predictions based upon a user input string. It can be used in conjunction with [Google Place Details] 17 | to validate user input and retrieve geographic information. Please refer to 18 | [Google's documentation](https://developers.google.com/places/web-service/autocomplete) for information about this service. 19 | 20 | NOTE: Aside from autocompleting user input, Place Autocomplete is also the geo service to use for validating or normalizing 21 | non-street address location types, such as cities or zip codes. 22 | 23 | ## Session Tokens and Usage Example 24 | 25 | All requests require a UUID session token. Session tokens are used by Google to group multiple 26 | requests into one billing session. 27 | 28 | As an example of the intended usage of sessions, suppose a consumer of the Place Autocomplete and [Place Details](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceDetails.md) apis has a 29 | user searching for a place: 30 | 31 | 1. A session token UUID `A` is generated for the session. 32 | 2. The user begins typing a place name. 33 | 3. On e.g. the third keystroke `"Har"` a request is sent to `/core/geography/place/autocomplete` with 34 | `input`: `Har` and `session_token`: `A`. 35 | 4. A list of predictions and their `place_id`s are generated for `"Har"` and returned in the response. 36 | 5. The user does not select any of the predictions and instead inputs another keystroke `"Harb"`. 37 | 6. `input`: `"Harb"` and `session_token`: `A` is sent in a new request. 38 | 7. A new list of predictions and their `place_id`s are generated and returned 39 | 8. The user selects one of the predictions. 40 | 9. The `place_id` for the selected prediction is sent to the Place Details service along with 41 | `session_token`: `A`. 42 | 10. Place Details returns geographic details (locality name, lat/lng, etc.) for the selected place. 43 | 11. A new session token is generated for any subsequent searches done by that user or any other 44 | users (i.e. DO NOT reuse session tokens). 45 | 46 | Using session tokens in this way greatly minimizes billing costs incurred. Please see [Google's session token 47 | documentation](https://developers.google.com/places/web-service/session-tokens) for more information. 48 | 49 | ## Request Structure 50 | 51 | Request structure for this service mirrors [Google's request structure](https://developers.google.com/places/web-service/autocomplete#place_autocomplete_requests). 52 | 53 | #### Request 54 | 55 | |Field|Type|Required|Example|Note| 56 | |----|----|----|----|----| 57 | |`input`|`string`|True|`"Harbi"`|| 58 | |`session_token`|`string`|True|-|Must be UUID.| 59 | |`language`|`string`|False|`"et"`|See [supported languages](https://developers.google.com/maps/faq#languagesupport)| 60 | |`components`|`array[string]`|False|`["US", "CA", "CN"]`|No more than 5 countries. Must be ISO 3166-1 Alpha-2| 61 | |`types`|`string`|False|`"(regions)"`|See [place types](https://developers.google.com/places/web-service/autocomplete#place_types)| 62 | 63 | #### Examples 64 | 65 | Only required fields w/ a city: 66 | ````json 67 | { 68 | "input": "Harbi", 69 | "session_token": "" 70 | } 71 | ```` 72 | 73 | Only required fields w/ a postal code: 74 | ````json 75 | { 76 | "input": "90210", 77 | "session_token": "" 78 | } 79 | ```` 80 | 81 | Only required fields w/ a country: 82 | ````json 83 | { 84 | "input": "China", 85 | "session_token": "" 86 | } 87 | ```` 88 | 89 | Only required fields w/ an address code: 90 | ````json 91 | { 92 | "input": "1600 Pennsylvania Avenue, washington dc", 93 | "session_token": "" 94 | } 95 | ```` 96 | 97 | All fields: 98 | ````json 99 | { 100 | "input": "Harbi", 101 | "session_token": "", 102 | "language": "zh-cn", 103 | "components": ["CN", "US", "CA", "ET", "FR"], 104 | "types": "(regions)" 105 | } 106 | ```` 107 | 108 | ## Response Structure 109 | 110 | The response contains a list of up to 5 predictions. 111 | 112 | Each prediction contains: 113 | - `description` string 114 | - `place_id` 115 | - List of `terms` and their `offset` 116 | - Location of the `matched_substring` in the prediction result 117 | - `structured_formatting`, pre-formatted text that can be used when displaying predictions 118 | - `distance_meters` from `origin` (if `origin` was specified in the request) 119 | 120 | Please see [Google's documentation](https://developers.google.com/places/web-service/autocomplete#place_autocomplete_results) 121 | for additional information on these fields. 122 | 123 | #### Example 124 | ```json 125 | { 126 | "data": { 127 | "predictions": [ 128 | { 129 | "description": "Harbin, 黑龙江省中国", 130 | "place_id": "ChIJYRRkpvhkQ14R1SygWnOSfF4", 131 | "types": [ 132 | "locality", 133 | "political", 134 | "geocode" 135 | ], 136 | "terms": [ 137 | { 138 | "offset": 0, 139 | "value": "Harbin" 140 | }, 141 | { 142 | "offset": 8, 143 | "value": "黑龙江省" 144 | }, 145 | { 146 | "offset": 12, 147 | "value": "中国" 148 | } 149 | ], 150 | "structured_formatting": { 151 | "main_text": "Harbin", 152 | "secondary_text": "黑龙江省中国", 153 | "main_text_matched_substrings": [ 154 | { 155 | "length": 4, 156 | "offset": 0 157 | } 158 | ] 159 | }, 160 | "matched_substring": [ 161 | { 162 | "length": 4, 163 | "offset": 0 164 | } 165 | ], 166 | "distance_meters": 5233 167 | }, 168 | { 169 | "description": "Nangang, 哈尔滨市黑龙江省中国", 170 | "place_id": "ChIJIcgm1bB5RF4RZA29COpGXqg", 171 | "types": [ 172 | "sublocality_level_1", 173 | "sublocality", 174 | "political", 175 | "geocode" 176 | ], 177 | "terms": [ 178 | { 179 | "offset": 0, 180 | "value": "Nangang" 181 | }, 182 | { 183 | "offset": 9, 184 | "value": "哈尔滨市" 185 | }, 186 | { 187 | "offset": 13, 188 | "value": "黑龙江省" 189 | }, 190 | { 191 | "offset": 17, 192 | "value": "中国" 193 | } 194 | ], 195 | "structured_formatting": { 196 | "main_text": "Nangang", 197 | "secondary_text": "哈尔滨市黑龙江省中国", 198 | "main_text_matched_substrings": [ 199 | { 200 | "length": 7, 201 | "offset": 0 202 | } 203 | ] 204 | }, 205 | "matched_substring": [ 206 | { 207 | "length": 7, 208 | "offset": 0 209 | } 210 | ], 211 | "distance_meters": 8416 212 | } 213 | ] 214 | } 215 | } 216 | ``` 217 | 218 | In the above example, the `place_id` value in the response could then be sent to [Place Details](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceDetails.md) to retrieve relevant geo information about this locality. Please see the [request](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceDetails.md#example-request) and [response](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceDetails.md#examples) sections of Place Details documentation, which continue the above example and show this locations place information. 219 | 220 | ## Versioning 221 | 222 | The current version of the service is 1.0. 223 | 224 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 225 | 226 | Our general versioning strategy is available [here](/Versioning.md). 227 | -------------------------------------------------------------------------------- /JobTitle.md: -------------------------------------------------------------------------------- 1 | Job Title Service 2 | ============= 3 | 4 | Table of Contents 5 | _________ 6 | - [Request Information](#request-information) 7 | - [Sample Response](#sample-response) 8 | - [Available Taxonomies](#taxonomies) 9 | - [Versioning](#versioning) 10 | 11 | 12 | # Request Information 13 | 14 | HTTP method: GET or POST (form or JSON) 15 | 16 | Parameters: 17 | 18 | * `taxonomy` (required) : classification taxonomy to use; accepted values are listed [here](#taxonomies). A single title/description may be classified against multiple taxonomies in a single request by providing multiple taxonomies in this parameter, separated by the pipe ("|") character (see example query below). 19 | * `title` (required if description is empty) : job title 20 | * `description` (required if title is empty) : job description 21 | 22 | Example: https://api.careerbuilder.com/core/classifier/jobtitle?title=Janitor&taxonomy=carotenev3_3_US|onet17 23 | # Sample Response 24 | ``` 25 | { 26 | "data": { 27 | "onet17": [ 28 | { 29 | "title": "Janitors and Cleaners, Except Maids and Housekeeping Cleaners", 30 | "id": "37-2011.00", 31 | "confidence": 95.0 32 | }, 33 | { 34 | "title": "First-Line Supervisors of Housekeeping and Janitorial Workers", 35 | "id": "37-1011.00", 36 | "confidence": 54.0 37 | } 38 | ], 39 | "carotenev3.3_us": [ 40 | { 41 | "title": "Janitor", 42 | "id": "37.1", 43 | "confidence": 1.0, 44 | "minor_title": "Building Cleaning and Pest Control Workers", 45 | "minor_id": "2000" 46 | }, 47 | { 48 | "title": "Assistant Landscaper", 49 | "id": "37.1083", 50 | "confidence": 0.0, 51 | "minor_title": "Supervisors of Building and Grounds Cleaning and Maintenance Workers", 52 | "minor_id": "1000" 53 | }, 54 | { 55 | "title": "Head Cleaner", 56 | "id": "37.1122", 57 | "confidence": 0.0, 58 | "minor_title": "Building Cleaning and Pest Control Workers", 59 | "minor_id": "2000" 60 | } 61 | ] 62 | } 63 | } 64 | ``` 65 | 66 | # Taxonomies 67 | Possible taxonomies (with links to full taxonomy results) 68 | 69 | | Taxonomy | description | 70 | |----------|--------------| 71 | | [onet17](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/oNet17.md) | Updated ONets | 72 | | [carotenev3](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/CaroteneV3.md) | Changes from Carotene v2.2 include 7 removals, 139 updates, and 1,386 new titles.
[CaroteneV2_2ToV3CrossWalk.md](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/CaroteneV2_2ToV3CrossWalk.md)
[Carotenev2.2 to v3 Crosswalk.xlsx](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/Carotenev2.2%20to%20v3%20Crosswalk.xlsx)| 73 | | [carotenev3.1](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/CaroteneV3.1.csv) | Changes from Carotene v3 include 4 additions, 78 updates, and 28 removals. Adds disambiguation to v3 and includes minor_title and minor_id fields for hierarchical classification.
[Carotenev3 to v3.1 Crosswalk.xlsx](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/Carotenev3%20to%20v3.1%20Crosswalk.xlsx) 74 | | carotenev3.3_us | Carotene taxonomy based on a deep-learning approach (v3.1 is hierarchal) for improved prediction of SOC major. This taxonomy was trained with U.S.-specific data. 75 | | carotenev3.3_uk | Same as _carotenev3.3_us_, but trained with data specific to U.K. 76 | 77 | Complete taxonomy lists can be found [here](https://github.com/cbdr/DataScienceAPITaxonomies/tree/master/JobTitle) (restricted to CBReadOnly). 78 | 79 | # Versioning 80 | ----------- 81 | JobTitle versions the API contract and taxonomies separately. The API version controls the format of the API call and response. The taxonomy version controls what data is returned for the call. The current API version is 1.0. 82 | 83 | Both the Carotene and ONet taxonomies are strongly and immutably versioned. For both systems, the underlying classifiers may occasionally be updated without a version change. This may slightly change the classification results for some inputs, but will not affect the underlying taxonomy data. 84 | 85 | Our general versioning strategy is available [here](/Versioning.md). 86 | 87 | 88 | Job Title Batch Service 89 | ============= 90 | 91 | Table of Contents 92 | _________ 93 | - [Request Information](#batch-request-information) 94 | - [Sample Response](#batch-sample-response) 95 | - [Available Taxonomies](#batch-taxonomies) 96 | 97 | 98 | # Batch Request Information 99 | 100 | HTTP method: POST (JSON) 101 | ``` 102 | { 103 | "requests": [ 104 | {"title": "Management Analysts", "description": ""}, 105 | {"title":"Computer Systems Engineers","description":""} 106 | ], 107 | "taxonomy":"ONET17|CAROTENEV3_3_US" 108 | } 109 | ``` 110 | Parameters: 111 | * `taxonomy` (required) : classification taxonomy to use; accepted values are [here](#taxonomies). A single/multiple title/description may be classified against multiple taxonomies in a single request by providing multiple taxonomies in this parameter, separated by the pipe ("|") character (see example query below). 112 | * `requests` (required) a list of job titles or descriptions. Maximum of 100 titles/descriptions. 113 | * `title` (required if description is empty) : job title 114 | * `description` (required if title is empty) : job description 115 | 116 | Example: https://api.careerbuilder.com/core/classifier/jobtitle-batch 117 | # Batch Sample Response 118 | ``` 119 | { 120 | "data": { 121 | "classifications": [ 122 | { 123 | "onet17": [ 124 | { 125 | "title": "Management Analysts", 126 | "id": "13-1111.00", 127 | "confidence": 90.0 128 | }, 129 | { 130 | "title": "Computer Systems Analysts", 131 | "id": "15-1121.00", 132 | "confidence": 54.0 133 | } 134 | ], 135 | "carotenev3.3_us": [ 136 | { 137 | "title": "Requirements Management Analyst", 138 | "id": "15.272", 139 | "confidence": 0.44, 140 | "minor_title": "Computer Occupations", 141 | "minor_id": "1100" 142 | } 143 | ] 144 | }, 145 | { 146 | "onet17": [ 147 | { 148 | "title": "Software Developers, Systems Software", 149 | "id": "15-1133.00", 150 | "confidence": 93.0 151 | } 152 | ], 153 | "carotenev3.3_us": [ 154 | { 155 | "title": "Computer Systems Specialist", 156 | "id": "15.144", 157 | "confidence": 0.95, 158 | "minor_title": "Computer Occupations", 159 | "minor_id": "1100" 160 | } 161 | ] 162 | } 163 | ] 164 | } 165 | } 166 | ``` 167 | 168 | # Batch Taxonomies 169 | Possible taxonomies (with links to full taxonomy results) 170 | 171 | | Taxonomy | description | 172 | |-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| 173 | | [onet17](https://github.com/cbdr/DataScienceAPITaxonomies/blob/master/JobTitle/oNet17.md) | Updated ONets | 174 | | carotenev3.3_us | Carotene taxonomy based on a deep-learning approach (v3.1 is hierarchal) for improved prediction of SOC major. This taxonomy was trained with U.S.-specific data. | 175 | | carotenev3.3_uk | Same as _carotenev3.3_us_, but trained with data specific to U.K. | 176 | 177 | -------------------------------------------------------------------------------- /PlaceDetails.md: -------------------------------------------------------------------------------- 1 | Place Details 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request Structure](#request-structure) 9 | - [Response Structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | Place Details (`/core/geography/place/details`) is a wrapper service for 15 | [Google's Place Details API.](https://developers.google.com/places/web-service/details), which 16 | returns geographic and place information for a given [place ID](https://developers.google.com/places/web-service/place-id). 17 | 18 | ## Request Structure 19 | 20 | Request structure for this service mirrors 21 | [Google's request structure](https://developers.google.com/places/web-service/details#PlaceDetailsRequests), 22 | with a few notable exceptions: 23 | 24 | 1. `session_token` is required. 25 | 2. At least one `fields` value is required. 26 | 3. Not all `fields` are supported. 27 | 28 | #### Supported `fields` 29 | 30 | | `field` name | Supported? | 31 | |------------|------------| 32 | |`address_component`|`true`| 33 | |`adr_address`|`true`| 34 | |`business_status`|`true`| 35 | |`formatted_address`|`true`| 36 | |`geometry/location`|`true`| 37 | |`geometry/viewport`|`true`| 38 | |`icon`|`false`| 39 | |`name`|`true`| 40 | |`photo`|`false`| 41 | |`place_id`|`true`| 42 | |`plus_code`|`true`| 43 | |`type`|`true`| 44 | |`url`|`true`| 45 | |`utc_offset`|`true`| 46 | |`vicinity`|`true` 47 | |`formatted_phone_number`†|`true`| 48 | |`international_phone_number`†|`true`| 49 | |`opening_hours`|`false`| 50 | |`website`†|`true` 51 | |`price_level`|`false`| 52 | |`rating`|`false`| 53 | |`review`|`false`| 54 | |`user_ratings_total`|`false`| 55 | 56 | † Note that `formatted_phone_number`, `international_phone_number` and `website` are __billed at a 57 | higher rate__ than other fields. Consider omitting these fields from your request if they are not 58 | needed. 59 | 60 | If you would like to request support for any of the currently unsupported fields, contact DSAD at 61 | [DataScienceApplicationDevelopment@careerbuilder.com](DataScienceApplicationDevelopment@careerbuilder.com). 62 | 63 | #### Request Fields 64 | 65 | |Field|Type|Required|Example|Note| 66 | |----|----|----|----|----| 67 | |`place_id`|`string`|True|`"ChIJIcgm1bB5RF4RZA29COpGXqg"`|| 68 | |`session_token`|`string`|True|-|Must be UUID| 69 | |`fields`|`array[string]`|True|`["name", "address_component"]`|At least one field is required. See [Google's documentation on `fields`](https://developers.google.com/places/web-service/place-data-fields) and [results](https://developers.google.com/places/web-service/details#PlaceDetailsResults) for more information.| 70 | |`language`|`string`|False|`"et"`|See [supported languages](https://developers.google.com/maps/faq#languagesupport)| 71 | 72 | #### Example Request 73 | 74 | ```json 75 | { 76 | "place_id": "ChIJYRRkpvhkQ14R1SygWnOSfF4", 77 | "session_token": "", 78 | "fields": [ 79 | "address_component", 80 | "adr_address", 81 | "business_status", 82 | "formatted_address", 83 | "formatted_phone_number", 84 | "geometry/location", 85 | "geometry/viewport", 86 | "international_phone_number", 87 | "name", 88 | "place_id", 89 | "plus_code", 90 | "types", 91 | "url", 92 | "utc_offset", 93 | "vicinity", 94 | "website" 95 | ], 96 | "language": "et" 97 | } 98 | ``` 99 | 100 | ## Response Structure 101 | 102 | Please refer to Google's Place Details [Response](https://developers.google.com/places/web-service/details#PlaceDetailsResponses) 103 | and [Results](https://developers.google.com/places/web-service/details#PlaceDetailsResults) 104 | for a description of the various response fields. 105 | 106 | ### Examples 107 | 108 | #### Locality 109 | 110 | ```json 111 | { 112 | "data": { 113 | "address_components": [ 114 | { 115 | "long_name": "Harbin", 116 | "short_name": "Harbin", 117 | "types": [ 118 | "LOCALITY", 119 | "POLITICAL" 120 | ] 121 | }, 122 | { 123 | "long_name": "Heilongjiang", 124 | "short_name": "Heilongjiang", 125 | "types": [ 126 | "ADMINISTRATIVE_AREA_LEVEL_1", 127 | "POLITICAL" 128 | ] 129 | }, 130 | { 131 | "long_name": "Hiina", 132 | "short_name": "CN", 133 | "types": [ 134 | "COUNTRY", 135 | "POLITICAL" 136 | ] 137 | } 138 | ], 139 | "adr_address": "Harbin, Heilongjiang, Hiina", 140 | "formatted_address": "Harbin, Heilongjiang, Hiina", 141 | "geometry": { 142 | "location": { 143 | "latitude": 45.803775, 144 | "longitude": 126.534967 145 | }, 146 | "viewport": { 147 | "northeast": { 148 | "latitude": 45.8838096, 149 | "longitude": 126.8799341 150 | }, 151 | "southwest": { 152 | "latitude": 45.6306503, 153 | "longitude": 126.4241087 154 | } 155 | } 156 | }, 157 | "name": "Harbin", 158 | "place_id": "ChIJYRRkpvhkQ14R1SygWnOSfF4", 159 | "types": [ 160 | "LOCALITY", 161 | "POLITICAL" 162 | ], 163 | "url": "https://maps.google.com/?q=Harbin,+Heilongjiang,+Hiina&ftid=0x5e4364f8a6641461:0x5e7c92735aa02cd5", 164 | "utc_offset": 480, 165 | "vicinity": "Harbin", 166 | "website": "http://www.harbin.gov.cn/" 167 | } 168 | } 169 | ``` 170 | 171 | #### Business 172 | 173 | ```json 174 | { 175 | "data": { 176 | "address_components": [ 177 | { 178 | "long_name": "5231", 179 | "short_name": "5231", 180 | "types": [ 181 | "STREET_NUMBER" 182 | ] 183 | }, 184 | { 185 | "long_name": "Buford Highway Northeast", 186 | "short_name": "Buford Hwy NE", 187 | "types": [ 188 | "ROUTE" 189 | ] 190 | }, 191 | { 192 | "long_name": "Doraville", 193 | "short_name": "Doraville", 194 | "types": [ 195 | "LOCALITY", 196 | "POLITICAL" 197 | ] 198 | }, 199 | { 200 | "long_name": "DeKalb County", 201 | "short_name": "Dekalb County", 202 | "types": [ 203 | "ADMINISTRATIVE_AREA_LEVEL_2", 204 | "POLITICAL" 205 | ] 206 | }, 207 | { 208 | "long_name": "Georgia", 209 | "short_name": "GA", 210 | "types": [ 211 | "ADMINISTRATIVE_AREA_LEVEL_1", 212 | "POLITICAL" 213 | ] 214 | }, 215 | { 216 | "long_name": "Ameerika Ühendriigid", 217 | "short_name": "US", 218 | "types": [ 219 | "COUNTRY", 220 | "POLITICAL" 221 | ] 222 | }, 223 | { 224 | "long_name": "30340", 225 | "short_name": "30340", 226 | "types": [ 227 | "POSTAL_CODE" 228 | ] 229 | } 230 | ], 231 | "adr_address": "5231 Buford Hwy NE, Doraville, GA 30340, Ameerika Ühendriigid", 232 | "business_status": "OPERATIONAL", 233 | "formatted_address": "5231 Buford Hwy NE, Doraville, GA 30340, Ameerika Ühendriigid", 234 | "formatted_phone_number": "(678) 691-2175", 235 | "geometry": { 236 | "location": { 237 | "latitude": 33.8948497, 238 | "longitude": -84.2819859 239 | }, 240 | "viewport": { 241 | "northeast": { 242 | "latitude": 33.8962456802915, 243 | "longitude": -84.2807332197085 244 | }, 245 | "southwest": { 246 | "latitude": 33.89354771970851, 247 | "longitude": -84.2834311802915 248 | } 249 | } 250 | }, 251 | "international_phone_number": "+1 678-691-2175", 252 | "name": "LanZhou Ramen 兰州拉面", 253 | "place_id": "ChIJZ8obVM4J9YgR_JlLF3EF1EM", 254 | "plus_code": { 255 | "global_code": "865QVPV9+W6", 256 | "compound_code": "VPV9+W6 Doraville, GA, Ameerika Ühendriigid" 257 | }, 258 | "types": [ 259 | "RESTAURANT", 260 | "FOOD", 261 | "POINT_OF_INTEREST", 262 | "ESTABLISHMENT" 263 | ], 264 | "url": "https://maps.google.com/?cid=4887537478884104700", 265 | "utc_offset": -240, 266 | "vicinity": "5231 Buford Highway Northeast, Doraville", 267 | "website": "http://lanzhouramenatlanta.com/" 268 | } 269 | } 270 | ``` 271 | 272 | 273 | ## Versioning 274 | 275 | The current version of the service is 1.0. 276 | 277 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 278 | 279 | Our general versioning strategy is available [here](/Versioning.md). 280 | -------------------------------------------------------------------------------- /Skills.md: -------------------------------------------------------------------------------- 1 | # Semantic Skills Tagging API 2 | 3 | The Semantic Skills Tagging service (available at https://api.careerbuilder.com/core/tagging/skills) takes raw text and tags surface forms of skills which appear in the text, returning a list of normalized skills and a confidence score. 4 | 5 | This API supports the HTTP/GET and HTTP/POST methods. 6 | 7 | Currently supported versions are 4.1, 4.2, 5.0, and 8.0. Version is passed in the `Accept` header as the parameter version (E.g. ```Accept:application/json;version=8.0```). 8 | 9 | **For versions < 8.0, this API is also available as a locally-runnable JAR. Clients with JVM-based applications may find this useful to avoid the overhead of repeated network calls. More information can be found [here](https://github.com/cbdr/SkillsExtractor).** 10 | 11 | Taxonomies can be found through the [Taxonomy API](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/TaxonomyService.md). 12 | 13 | Request 14 | ------- 15 | 16 | | Parameter | 4.1 | 4.2 | 5.0 | 8.0 | Description | Default value | 17 | |-----------------------|------------------------|----------------------|----------------------|----------------------|-------|------| 18 | | `version` | Required | Required | Required | Required | Passed in via the Accept header. Possible values are "4.1", "4.2", or "5.0". | - | 19 | | `content` | Required | Required | Required | Required* | A string containing the content to be tagged | - | 20 | | `language` | Optional | Optional | Optional | Optional | A string containing an ISO 639-1 code indicating the language in which the input text is written. If `language` is not provided in the request then English is used as the default. | English | 21 | | `threshold` | Optional† | Optional† | Optional† | Optional | A double value between 0 and 1 controlling minimum relevancy scores for skill recognition. Higher values will more tightly restrict the returned skill tags. A threshold of 0 means all seed skill phrases recognized by exact string matching will be returned. | 0.5 | 22 | | `auto_threshold` | Optional | Optional | Optional | - | A boolean value indicating whether automatic thresholding is desired. If enabled, then when input text contains 150 or fewer words, the threshold parameter will be overwritten to 0 and all confidence values will be overwritten to 1.0‡. Default is true. Note that this parameter is only supported for inputs in en, fr, and de. | - | 23 | | `return_related_skills` | Optional | Optional | Optional | - | A boolean value indicating whether to return related skills for each extracted skill. Defaults to false. Related skills contain the same fields as extracted skills, with confidence scores indicating their relevance to the extracted skill. | - | 24 | 25 | * In version 8.0 the `content` field has a limit of 50,000 characters after which subsequent characters are ignored. 26 | 27 | † Prior to version 8.0 `threshold` was only supported for English `content`. 28 | 29 | ‡ A more detailed explanation of this functionality: The tagger uses “context” to define semantic relevancy. If the input is too short (<= 150 words) to constitute a “context,” the tagger by default returns everything by direct matching, resulting in 0.0 confidence scores due to lack of context for relatedness. To avoid confusion, a pseudo score “1” is assigned to indicate “directly matched.” This feature is called “auto thresholding”. 30 | 31 | #### Example request 32 | 33 | ``` 34 | curl -L -X POST 'https://wwwtest.api.careerbuilder.com/core/tagging/skills' \ 35 | -H 'Accept: application/json;version=8.0' \ 36 | -H 'Content-Type: application/json' \ 37 | -H 'Authorization: ' \ 38 | --data-raw '{ 39 | "content": "sed (\"stream editor\") is a Unix utility that parses and transforms text, using a simple, compact programming language. sed was developed from 1973 to 1974 by Lee E. McMahon of Bell Labs,[1] and is available today for most operating systems.", 40 | "language": "en", 41 | "threshold": 0.91 42 | }' 43 | ``` 44 | 45 | 46 | Response 47 | -------- 48 | 49 | The returned response contains only normalized names in accordance with Wikipedia. All returned skills are sorted first by relevancy and then alphabetically. 50 | 51 | The response structure of version 8.0 differs slightly from previous version. 52 | 53 | ## 8.0 54 | 55 | ``` 56 | { 57 | "data": { 58 | "meta": { 59 | "taxonomy_version": "2020-12-22T08:42:47" 60 | }, 61 | "skills": [ 62 | { 63 | "type": "IT Skill", 64 | "skilldid": "KS120076FGP5WGWYMP0F", 65 | "normalized_term": "Java (Programming Language)", 66 | "matches": [ 67 | { 68 | "begin": 15, 69 | "end": 18, 70 | "likelihood": 1.0, 71 | "surface_form": "java" 72 | } 73 | ], 74 | "confidence": 1.0 75 | } 76 | ], 77 | "truncated": false, 78 | "version": "2.2.0" 79 | } 80 | } 81 | ``` 82 | 83 | - `matches` contains matched `surface_form`s for a given `normalized_term` and the character positions in the request's `content` field at which the `surface_form` begins and ends. 84 | - `likelihood` and `confidence` range between 0.0 and 1.0. 85 | - Possible `type` values: 86 | - Certification 87 | - IT Skill 88 | - Language 89 | - Professional Skill 90 | - Soft Skill 91 | - `truncated` will be `true` if the request's `content` field was larger than the aforementioned 50,000 character limit. 92 | 93 | 94 | ## 4.1, 4.2, 5.0 95 | 96 | 97 | ``` 98 | { 99 | "response": [ 100 | { 101 | "skilldid": "KS120076FGP5WGWYMP0F", 102 | "skill_id": "KSH9TO", 103 | "normalized_term": "Apache Hadoop (Hadoop)", 104 | "confidence": 1, 105 | "type": "Hard Skill", 106 | "related_skills": [ 107 | { 108 | "skilldid": "KS124KT6K427LFSF9NQC", 109 | "skill_id": "KSYFG5", 110 | "normalized_term": "MapReduce", 111 | "confidence": 0.830889, 112 | "type": "Hard Skill" 113 | }, 114 | (...) 115 | ] 116 | } 117 | ] 118 | } 119 | ``` 120 | 121 | Note that if `return_related_skills` is not set on the request then no `related_skills` will be present on the response. 122 | 123 | ## Error 124 | 125 | ``` 126 | { 127 | "errors": [ 128 | { 129 | "type": "empty content", 130 | "message": "content must be provided.", 131 | "code": 0 132 | } 133 | ] 134 | } 135 | ``` 136 | 137 | Languages 138 | ----------- 139 | 140 | The following table lists available languages and which versions they are available in. 141 | 142 | | Language | [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) | <=5.0 | 8.0 | 143 | |-------------|-------------------------------------------------------------------------|-------|-----| 144 | | Bulgarian | bg | ✓ | | 145 | | Czech | cs | ✓ | | 146 | | Danish | da | ✓ | | 147 | | Dutch | nl | ✓ | ✓ | 148 | | English | en | ✓ | ✓ | 149 | | Estonian | et | ✓ | | 150 | | Finnish | fi | ✓ | | 151 | | French | fr | ✓ | ✓ | 152 | | German | de | ✓ | ✓ | 153 | | Greek | el | ✓ | | 154 | | Hungarian | hu | ✓ | | 155 | | Italian | it | ✓ | ✓ | 156 | | Latvian | lv | ✓ | | 157 | | Lithuanian | lt | ✓ | | 158 | | Maltese | mt | ✓ | | 159 | | Polish | pl | ✓ | | 160 | | Portuguese | pt | ✓ | | 161 | | Romanian | ro | ✓ | | 162 | | Sinhala | si | ✓ | | 163 | | Slovak | sk | ✓ | | 164 | | Spanish | es | ✓ | ✓ | 165 | | Swedish | sv | ✓ | | 166 | 167 | Versioning 168 | ----------- 169 | The data returned is versioned. The current version is 8.0. A version must be supplied to this service; if no version is supplied, a 400 Bad Request error will be returned. 170 | 171 | Our general versioning strategy is available [here](/Versioning.md). 172 | 173 | -------------------------------------------------------------------------------- /PlaceAutocompleteDetails.md: -------------------------------------------------------------------------------- 1 | Place Autocomplete Details 2 | ========================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request Structure](#request-structure) 9 | - [Response Structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | Place Autocomplete Details (`/core/geography/place/autocompletedetails`) service that wraps the functionalities of both the Place Autocomplete 15 | and Place Details APIs. The Place Autocomplete API generates place predictions based on user input, and for the first prediction, 16 | it invokes the Place Details API to retrieve the defined geographic and place fields ie `address_components`, `formatted_address`, 17 | `geometry`, `place_id` and `types`. 18 | 19 | 20 | ## Request Structure 21 | 22 | |Field|Type|Required|Example|Note| 23 | |----|----|----|----|----| 24 | |`input`|`string`|True|`"Harbi"`|| 25 | |`session_token`|`string`|True|-|Must be UUID.| 26 | 27 | #### Examples 28 | 29 | ````json 30 | { 31 | "input": "La rochette", 32 | "session_token": "" 33 | } 34 | ```` 35 | 36 | ## Response Structure 37 | 38 | The response contains a detail response 39 | 40 | Each detail response contains: 41 | - `address_components` 42 | - `place_id` 43 | - `formatted_address` 44 | - `geometry` 45 | - `types` 46 | 47 | #### Example 48 | ```json 49 | { 50 | "data": { 51 | "geo": { 52 | "address_components": [ 53 | { 54 | "long_name": "La Rochette", 55 | "short_name": "La Rochette", 56 | "types": [ 57 | "LOCALITY", 58 | "POLITICAL" 59 | ] 60 | }, 61 | { 62 | "long_name": "Seine-et-Marne", 63 | "short_name": "Seine-et-Marne", 64 | "types": [ 65 | "ADMINISTRATIVE_AREA_LEVEL_2", 66 | "POLITICAL" 67 | ] 68 | }, 69 | { 70 | "long_name": "Île-de-France", 71 | "short_name": "IDF", 72 | "types": [ 73 | "ADMINISTRATIVE_AREA_LEVEL_1", 74 | "POLITICAL" 75 | ] 76 | }, 77 | { 78 | "long_name": "France", 79 | "short_name": "FR", 80 | "types": [ 81 | "COUNTRY", 82 | "POLITICAL" 83 | ] 84 | }, 85 | { 86 | "long_name": "77000", 87 | "short_name": "77000", 88 | "types": [ 89 | "POSTAL_CODE" 90 | ] 91 | } 92 | ], 93 | "formatted_address": "77000 La Rochette, France", 94 | "geometry": { 95 | "location": { 96 | "latitude": 48.508348, 97 | "longitude": 2.662553 98 | } 99 | }, 100 | "place_id": "ChIJmQVNw7_w5UcRYXRdIUEpBgo", 101 | "types": [ 102 | "LOCALITY", 103 | "POLITICAL" 104 | ] 105 | } 106 | } 107 | } 108 | ``` 109 | 110 | ## Versioning 111 | 112 | The current version of the service is 1.0. 113 | 114 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 115 | 116 | Our general versioning strategy is available [here](/Versioning.md). 117 | 118 | # Batch Place Autocomplete Details With CallBack 119 | 120 | 121 | #### Table of Contents 122 | _______ 123 | 124 | - [Summary](#batch-autocomplete-summary) 125 | - [Request Structure](#batch-request) 126 | - [Response Structure](#batch-response) 127 | - [CallBack Response Structure](#callback-response) 128 | - [CallBack Error Response Structure](#callback-error-response) 129 | - [Versioning](#batch-versioning) 130 | 131 | ## Batch Autocomplete Summary 132 | 133 | Place Autocomplete Details (`/core/geography/place/autocompletedetails-batch`) is for batch processing 134 | and accepts a list of inputs. It wraps the functionalities of both the Place Autocomplete and Place Details APIs. 135 | The Place Autocomplete API generates place predictions corresponding to the provided input. 136 | Subsequently, from the list of predictions, the service selects the first prediction 137 | and then triggers the Place Details API to retrieve the defined geographic and place fields ie 138 | `address_components`, `formatted_address`, `geometry`, `place_id` and `types` providing an aggregated information 139 | of all the inputs and is posted to the specified `call_back_uri`. 140 | 141 | 142 | ## Batch Request 143 | The API accepts a list of inputs along with an ID. 144 | 145 | ````json 146 | { 147 | "geo":[ 148 | { 149 | "id":"bjea562179-169a-5dea-b87f-f08010b9cbfc", 150 | "input":"chicago" 151 | }, 152 | { 153 | "id":"ajea562179-069a-4dea-a87f-e08010b9cbfc", 154 | "input":"norcross" 155 | } 156 | ], 157 | "session_token": "", 158 | "call_back_uri": "https://api.careerbuilder.com/handle_call_back" 159 | } 160 | ```` 161 | **Note**: Ensure that the `call_back_uri` is a valid URI routed through the Zuul layer. 162 | 163 | ## Batch Response 164 | Upon receiving a request, the API immediately validates the request information which includes `call_back_uri` and return 165 | a 200 response, ensuring that the request was successfully received. 166 | 167 | #### Example 168 | ```json 169 | { 170 | "data": { 171 | "status": "OK", 172 | "call_back_uri": "https://api.careerbuilder.com/handle_call_back" 173 | } 174 | } 175 | ``` 176 | 177 | ## CallBack Response 178 | Following the initial response, the API proceeds to process each input. For the first prediction generated 179 | by the Autocomplete API, the API queries the Details endpoint to retrieve the defined geographic and 180 | place information. Once all inputs are processed, the API posts a response to the specified `call_back_uri` URL, 181 | providing the aggregated information. 182 | 183 | #### Example 184 | ```json 185 | [ 186 | { 187 | "id":"bjea562179-169a-5dea-b87f-f08010b9cbfc", 188 | "geo":{ 189 | "address_components":[ 190 | { 191 | "long_name":"Chicago", 192 | "short_name":"Chicago", 193 | "types":[ 194 | "LOCALITY", 195 | "POLITICAL" 196 | ] 197 | }, 198 | { 199 | "long_name":"Cook County", 200 | "short_name":"Cook County", 201 | "types":[ 202 | "ADMINISTRATIVE_AREA_LEVEL_2", 203 | "POLITICAL" 204 | ] 205 | }, 206 | { 207 | "long_name":"Illinois", 208 | "short_name":"IL", 209 | "types":[ 210 | "ADMINISTRATIVE_AREA_LEVEL_1", 211 | "POLITICAL" 212 | ] 213 | }, 214 | { 215 | "long_name":"United States", 216 | "short_name":"US", 217 | "types":[ 218 | "COUNTRY", 219 | "POLITICAL" 220 | ] 221 | } 222 | ], 223 | "formatted_address":"Chicago, IL, USA", 224 | "geometry":{ 225 | "location":{ 226 | "latitude":41.8781136, 227 | "longitude":-87.6297982 228 | } 229 | }, 230 | "place_id":"ChIJ7cv00DwsDogRAMDACa2m4K8", 231 | "types":[ 232 | "LOCALITY", 233 | "POLITICAL" 234 | ], 235 | "metropolitan_statistical_area":{ 236 | "title":"Chicago-Naperville-Elgin, IL-IN-WI", 237 | "code":16980 238 | }, 239 | "designated_market_areas":[ 240 | { 241 | "name":"Chicago, IL", 242 | "id":602 243 | } 244 | ] 245 | } 246 | }, 247 | { 248 | "id":"ajea562179-069a-4dea-a87f-e08010b9cbfc", 249 | "geo":{ 250 | "address_components":[ 251 | { 252 | "long_name":"Norcross", 253 | "short_name":"Norcross", 254 | "types":[ 255 | "LOCALITY", 256 | "POLITICAL" 257 | ] 258 | }, 259 | { 260 | "long_name":"Gwinnett County", 261 | "short_name":"Gwinnett County", 262 | "types":[ 263 | "ADMINISTRATIVE_AREA_LEVEL_2", 264 | "POLITICAL" 265 | ] 266 | }, 267 | { 268 | "long_name":"Georgia", 269 | "short_name":"GA", 270 | "types":[ 271 | "ADMINISTRATIVE_AREA_LEVEL_1", 272 | "POLITICAL" 273 | ] 274 | }, 275 | { 276 | "long_name":"United States", 277 | "short_name":"US", 278 | "types":[ 279 | "COUNTRY", 280 | "POLITICAL" 281 | ] 282 | } 283 | ], 284 | "formatted_address":"Norcross, GA, USA", 285 | "geometry":{ 286 | "location":{ 287 | "latitude":33.9411081, 288 | "longitude":-84.2137443 289 | } 290 | }, 291 | "place_id":"ChIJqTKlbTih9YgRVjJ2xmfcfJQ", 292 | "types":[ 293 | "LOCALITY", 294 | "POLITICAL" 295 | ], 296 | "metropolitan_statistical_area":{ 297 | "title":"Atlanta-Sandy Springs-Alpharetta, GA", 298 | "code":12060 299 | }, 300 | "designated_market_areas":[ 301 | { 302 | "name":"Atlanta, GA", 303 | "id":524 304 | } 305 | ] 306 | } 307 | } 308 | ] 309 | ``` 310 | If no predictions found: 311 | ```json 312 | [ 313 | { 314 | "id":"bjea562179-169a-5dea-b87f-f08010b9cbfc", 315 | "geo":{} 316 | }, 317 | { 318 | "id":"ajea562179-069a-4dea-a87f-e08010b9cbfc", 319 | "geo":{} 320 | } 321 | ] 322 | ``` 323 | 324 | ## CallBack Error Response 325 | If any error happens during the process, error response will be posted to the given `call_back_uri`. 326 | Errors may originate from two services, autocomplete and details. 327 | In the case of an error from the autocomplete service, the response structure is: 328 | Ex: 329 | ```json 330 | [ 331 | { 332 | "id":"bjea562179-169a-5dea-b87f-f08010b9cbfc", 333 | "error":"An error occurred in the autocomplete service", 334 | "geo":{} 335 | } 336 | ] 337 | ``` 338 | In the case of an error from the details service, the response structure is: 339 | 340 | ```json 341 | [ 342 | { 343 | "id":"bjea562179-169a-5dea-b87f-f08010b9cbfc", 344 | "error":"An error occurred in the details service", 345 | "geo":{} 346 | } 347 | ] 348 | ``` 349 | For errors originating from the autocompletedetails service, the response structure is: 350 | ```json 351 | {"error": "bad gateway"} 352 | ``` 353 | 354 | ## Batch Versioning 355 | 356 | The current version of the service is 1.0. 357 | 358 | Version must be specified in the Accept header. E.g. `application/json;version=1.0`. 359 | 360 | Our general versioning strategy is available [here](/Versioning.md). -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | This repository houses documentation for the APIs published by CareerBuilder's Data Science Application Development (DSAD) team. Each API's application-specific documentation resides in a `.md` file bearing the service's name, e.g. `Skills.md` contains documentation on our Skills Extraction API. Application-specific documentation will generally include design principles and goals of the API, a description of the API's request and response structure(s), and (if applicable) a Frequently Asked Questions section for clarifying common questions with the API. 4 | 5 | Below, you will find general information pertaining to all DSAD APIs. **Please review this documentation, along with the relevant service-specific documentation, in full before starting to work with any DSAD APIs. By integrating with any of the APIs documented here, you indicate that you have reviewed the relevant documentation and agree to any obligations defined for our API clients.** 6 | 7 | ### Contact Information 8 | 9 | The Data Science Application Development team is the primary point of contact for API-related questions and concerns. The team can be reached at the following email: 10 | 11 | ![](/assets/dsad.png) 12 | 13 | Email inquiries will typically be handled within 1-2 business days, though it may occasionally take longer. For internal users who are part of the CareerBuilder HipChat organization, the team can also be reached via the DataSciAppDevPublic chat room (use @here or @all to ping team members). 14 | 15 | For after-hours emergencies concerning production systems, contact the following email. Note that this will trigger our team pager and possibly wake up an engineer -- as such, this email is only to be used for user-impacting production issues that cannot wait until business hours. 16 | 17 | ![](/assets/dsam.png) 18 | 19 | For questions concerning the CB API routing layer, including the OAuth flow described in the [Access](#access) section, contact the Authorization team at the following email: 20 | 21 | ![](/assets/authz.png) 22 | 23 | ### Environments 24 | 25 | Unless documented otherwise, all DSAD APIs are available in three environments: 26 | 27 | * **Staging** - All new APIs, endpoints, and features -- and changes to existing ones -- are deployed to staging before being deployed to production. The amount of wait time between staging and production deployments varies; typically several days to a week for large or high-risk changes; less for low-risk changes. 28 | 29 | Clients of DSAD's APIs are **required** to maintain staging integrations which mirror their production integrations and are sufficiently monitored by the client. DSAD regularly uses data from its staging environment to inform production decisions; for example, a new feature may first be released into staging, and if no issues are caught, then it may proceed into production. Clients who opt out of staging integrations therefore put their applications at risk of unexpected breakages. 30 | 31 | Note that the staging environment is currently maintained on a best-effort basis. Service outages occurring in Staging are not considered "on-call" events, and will be addressed as fast as reasonably possible during business hours. Production outages will always take precedence over staging outages. The DSAD team monitors staging in the same ways as production, but with slightly more relaxed thresholds. Clients are discouraged from tying critical paths to DSAD's staging environments, e.g. a client's CI/CD pipeline should not be dependent on DSAD staging environment availability. 32 | 33 | * **US Production** - The primary production environment for applications based in the Americas. Most CareerBuilder production systems will use this environment most of the time. 34 | 35 | * **EU Production** - A secondary production environment that is hosted entirely within Europe. Data transmitted through the EU Production API environment is guaranteed to remain within the physical bounds of Europe. This production environment therefore satisfies certain EU data privacy laws restricting transmission of European citizens' personal data outside of Europe. This environment may also provide reduced latency to applications located in Europe, Africa, and Asia. 36 | 37 | API environment access is determined in a standard way by modifying the "host" portion of the URL in a call to the API routing layer. The correct "host" for each API environment is as follows: 38 | 39 | | API Environment | Host | 40 | |----------|-------------| 41 | | Staging | `wwwtest.api.careerbuilder.com` | 42 | | US Production | `api.careerbuilder.com` | 43 | | EU Production | `api.careerbuilder.eu` | 44 | 45 | Our API routes and interfaces are identical across regions except for the "host" portion of the URL. (The exception to the rule is that staging and production will be temporarily out of sync whenever a change has been deployed to staging, but not yet to production.) Our API-specific documentation will refer to the US Production version of that API's route(s); simply adjust the "host" value accordingly to determine the proper Staging and EU Production route(s) for the API. 46 | 47 | ### Access 48 | 49 | DSAD APIs are generally not available for free and public use. Access is governed via the CB API routing layer, maintained by CareerBuilder's Authorization team. More specifically, DSAD APIs must be accessed via CareerBuilder's implementation of the OAuth 2.0 Client Credentials flow. This is described in detail [here](/assets/ExternalClientCredentials.pdf). 50 | 51 | DSAD clients are required to use a separate, dedicated pair of credentials in each application that consumes DSAD APIs. (An application consuming multiple DSAD APIs may reuse the same credential pair for all integrations.) These credentials must be kept secret and secure, and should not be shared with other clients. 52 | 53 | OAuth client credentials in CareerBuilder's authorization systems are stored with a contact email for the owning team or individual. DSAD requires that API clients keep this contact information up-to-date. This information is occasionally necessary for contacting users of DSAD APIs about upcoming releases, breaking changes, planned maintenance periods, etc. **DSAD reserves the right to revoke, without warning, API access for any client found to be noncompliant with these obligations.** 54 | 55 | ### SLAs 56 | 57 | DSAD does not currently publish formal SLAs around API availability or response time. The CareerBuilder standard is 99.5% availability in production; we typically do better than this. Clients with specific questions around average availability, response times, rate limits, etc. should reach out to the team for clarification. 58 | 59 | ### Versioning and Sunsetting 60 | 61 | Please see our [documentation page on versioning](/Versioning.md). 62 | 63 | ### Common Request/Response Notes 64 | 65 | Most DSAD APIs simply expose a "pure" function that transforms some input object into some output object. As such, most of our APIs do not adhere to strict RESTful standards for HTTP verbs. Except where otherwise noted, DSAD APIs respond to HTTP GET and HTTP POST requests identically; clients may use whichever HTTP verb they find most convenient. (For example, HTTP GET requests are easier to construct on the fly, but HTTP POST requests can support larger inputs, which may be a consideration for users of a service such as Resume Parse & Normalize, which receives input documents up to several MB in size.) 66 | 67 | All DSAD APIs return JSON responses and, where applicable, accept JSON request bodies. No other serialization formats are currently supported. 68 | 69 | Except where otherwise noted, DSAD APIs comply with CareerBuilder API standards with respect to request and response syntax. Specifically, all multi-word request and response field names are written in `lower_snake_case` and all successful API responses are returned as a JSON object with a single top-level "data" object field containing all other response data. Error responses are returned as a JSON object with a single top-level "errors" array field containing one or more objects, defined as follows: `{ type: String, message: String, code: int }`. 70 | 71 | ### Common Error Codes 72 | 73 | Following is a non-exhaustive list of error codes that may be returned by DSAD APIs. Most of our APIs can return most of these codes in the cases described here. Additional codes, or deviations from the behavior-to-code mappings defined here, may be described in API-specific documentation pages. 74 | 75 | Note that the CareerBuilder API routing layer or OAuth token endpoint may also occasionally return HTTP errors. Some of these codes are defined as part of the HTTP standard, and others are nonstandard codes introduced by CareerBuilder's Authorization team. The full list of API routing layer error codes and their definitions can be found [here](/assets/RoutingLayerErrorCodes.pdf). 76 | 77 | * **400 (Bad Request)** : The API request was missing a required field or was otherwise invalid. 78 | * **401 (Unauthorized)** : The API request was not authorized. The API may only accept requests from whitelisted client_ids, or the request may not have been transmitted through the CB API routing layer properly. 79 | * **404 (Not Found)** : The API request targeted a route (or a version of a route) that does not exist. 80 | * **405 (Method Not Allowed)** : The API request specified an HTTP method that is not supported by the targeted API route and version. 81 | * **429 (Too Many Requests)** : The client_id associated with this request has sent too many requests to this API recently, and the API's performance is beginning to degrade as a result. Please wait a few minutes before resuming API calls. 82 | * **500 (Internal Server Error)** : The API request was accepted, but failed to complete successfully due to an internal error within the API. This error should not occur under normal circumstances; if you encounter this, please contact the DSAD team. 83 | * **502 (Bad Gateway)** : The API request was accepted, but failed to complete successfully due to an error which occurred with an upstream provider called during request processing. This error should not occur under normal circumstances; if you encounter this, please contact the DSAD team. 84 | * **503 (Service Unavailable)** : The API was unable to accept your request. This typically happens when our internal infrastructure becomes overwhelmed or unhealthy, either due to excessive request volume or due to other issues which cause our servers to degrade. This error should not occur under normal circumstances; if you encounter this, please contact the DSAD team. 85 | * **504 (Gateway Timeout)** : The API request was accepted, but failed to complete successfully due to an upstream provider called during request processing failing to respond within the required time threshold. This error should not occur under normal circumstances; if you encounter this, please contact the DSAD team. 86 | 87 | ### Client Libraries 88 | 89 | To accelerate the development of new API integrations, DSAD publishes client libraries targeting Java and .NET runtime environments. These libraries are versioned and published into the CareerBuilder Artifactory repository. 90 | 91 | CareerBuilder's Artifactory repository is managed by the CloudOps team. Please reach out to this team for assistance with consuming libraries hosted in Artifactory. 92 | -------------------------------------------------------------------------------- /Autocomplete.md: -------------------------------------------------------------------------------- 1 | Autocomplete Service 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Examples](#examples) 11 | - [Versioning](#versioning) 12 | 13 | ## Summary 14 | 15 | DSAD's Autocomplete Service is an HTTP REST webservice for autocompleting queries on one of several possible taxonomies. Currently supported taxonomies and their relative API routes are as follows: 16 | 17 | | Taxonomy | Relative API Route | 18 | |----------|-------------| 19 | | Carotene V1 | `/core/autocomplete/carotenev1` | 20 | | Carotene V2 | `/core/autocomplete/carotenev2` | 21 | | Carotene V2.2 | `/core/autocomplete/carotenev2_2` | 22 | | Carotene V3 | `/core/autocomplete/carotenev3` | 23 | | Carotene V3.1 | `/core/autocomplete/carotenev3_1` | 24 | | NAICS 2007 | `/core/autocomplete/naics2007` | 25 | | Normalized Companies | `/core/autocomplete/normalizedcompanies` | 26 | | Normalized Majors | `/core/autocomplete/normalizedmajors` | 27 | | Normalized Schools | `/core/autocomplete/normalizedschools` | 28 | | ONet15 | `/core/autocomplete/onet15` | 29 | | ONet17 | `/core/autocomplete/onet17` | 30 | | Skills V4 | `/core/autocomplete/skillsv4` | 31 | | Skills V5 | `/core/autocomplete/skillsv5` | 32 | | Skills V8 | `/core/autocomplete/skillsv8` | 33 | | Multiple taxonomies | `/core/autocomplete/taxonomies` | 34 | 35 | ### Request Structure 36 | 37 | Most supported taxonomies follow the same simple request format that consists of the following fields: 38 | 39 | | Field | Description | Required? | 40 | |----------|-------------|-----------| 41 | | `query` | The text to be autocompleted. For example, the query "nur" on a Skills taxonomy may yield an autocomplete suggestion of "Nursing". | Yes | 42 | | `limit` | The number of results to be returned. Acceptable values are integers between 1 and 100 (inclusive). Defaults to 20. | No | 43 | 44 |   45 | 46 | The Normalized Schools taxonomy also uses an additional request parameter: 47 | 48 | | Field | Description | Required? | 49 | |----------|-------------|-----------| 50 | | `school_level` | The type of school to which the results should be limited. Accepted values are `secondary` and `postsecondary` (case-insensitive). | No | 51 | 52 | The Multi taxonomy endpoint needs the following additional parameter 53 | 54 | | Field | Description | Required? | 55 | |----------|-------------|-----------| 56 | | `taxnomies` | List of taxonomies used for retrieving autocomplete results based on the query param | Yes | 57 | 58 | 59 | Requests may be provided as HTTP GET requests with query parameters, or as HTTP POST requests with either URL-encoded form or JSON content. 60 | 61 | ### Response Structure 62 | 63 | All responses with an HTTP status of 200 will consist of a JSON object with a top-level `data` node containing the following: 64 | 65 | | Field | Description | 66 | |----------|-------------| 67 | | `results` | A JSON array containing zero or more result objects. Each result represents a normalized entity from the requested taxonomy. The result object structure is described in more detail below. | 68 | 69 |   70 | 71 | Normalized Company, Normalized Major, and Normalized School responses will also contain the following in the `data` node: 72 | 73 | | Field | Description | 74 | |----------|-------------| 75 | | `data_version` | A string representing the current version of data backing the autocomplete service for the selected taxonomy. This is typically represented as a string in the YYYY-MM-DD format, but this format is not guaranteed. | 76 | 77 |   78 | 79 | The structure of the result objects is as follows for all taxonomies supported by the service: 80 | 81 | | Field | Description | 82 | |----------|-------------| 83 | | `suggestion` | The autocompletion suggestion for the provided query. As an example, "Nursing" may be the value of this field for the query "nur" on a Skills taxonomy. | 84 | | `id` | The unique identifier string for this result. | 85 | 86 |   87 | 88 | Result objects for the Normalized Schools taxonomy also include an additional field: 89 | 90 | | Field | Description | 91 | |----------|-------------| 92 | | `school_level` | The type of the school entity, either `SECONDARY` or `POSTSECONDARY`. | 93 | 94 |   95 | 96 | Normalized Company, Major, and School entities maintain an internal "popularity" score and results for these taxonomies will be returned in descending sorted order according to this score. Other taxonomies are not scored in this way and will return their results in alphabetical order. 97 | 98 |   99 | 100 | For multiple taxonomies the response should have the following structure 101 | 102 | | Field | Description | 103 | |----------|-------------| 104 | | `results` | A JSON array containing zero or more result objects. Each result represents an object with a list of results from each requested taxonomy. The result object structure in this case will be very similar to the individual taxonomy response | 105 | 106 | 107 | All responses will be returned as JSON. 108 | 109 | ## Examples 110 | 111 | Following are several request-response examples that demonstrate usage of the service. These examples are accompanied with links to the CB API tester page that demonstrate the requests in action. Note that you must be connected to the internal CB network and add the "API Management" Okta application to your Okta profile in order to access the API tester page. 112 | 113 | **Carotene V3 autocompletion for "account" with maximum 3 results [link](https://apimanagement.cbplatform.link/#routes/tester?preURL=https%3A%2F%2Fapi.careerbuilder.com%2F&postURL=core%2Fautocomplete%2Fcarotenev3%3Fquery%3Daccount%26limit%3D3&method=get&contentType=application%2Fjson&acceptType=application%2Fjson&version=1.0®ion=productionus&flow=client_credentials&userDid=&accountDid=&headers=&body=)** 114 | 115 | **Request** 116 | 117 | `https://www.api.careerbuilder.com/core/autocomplete/carotenev3?query=account&limit=3` 118 | 119 | **Response** 120 | ```json 121 | { 122 | "data": { 123 | "results": [ 124 | { 125 | "suggestion": "Accountant", 126 | "id": "13.0" 127 | }, 128 | { 129 | "suggestion": "Account Leader", 130 | "id": "41.10310" 131 | }, 132 | { 133 | "suggestion": "Account Liaison", 134 | "id": "41.30981" 135 | } 136 | ] 137 | } 138 | } 139 | ``` 140 | 141 |   142 | 143 | **Normalized Company autocompletion for "careerb" [link](https://apimanagement.cbplatform.link/#routes/tester?preURL=https%3A%2F%2Fapi.careerbuilder.com%2F&postURL=core%2Fautocomplete%2Fnormalizedcompanies%3Fquery%3Dcareerb&method=get&contentType=application%2Fjson&acceptType=application%2Fjson&version=1.0®ion=productionus&flow=client_credentials&userDid=&accountDid=&headers=&body=)** 144 | 145 | **Request** 146 | 147 | `https://www.api.careerbuilder.com/core/autocomplete/normalizedcompanies?query=careerb` 148 | 149 | **Response** 150 | ```json 151 | { 152 | "data": { 153 | "results": [ 154 | { 155 | "suggestion": "Careerbuilder, LLC", 156 | "id": "NC842f69a0-b621-48f6-b53c-9b3301e9aab7" 157 | } 158 | ], 159 | "data_version": "2018-03-15" 160 | } 161 | } 162 | ``` 163 | 164 |   165 | 166 | **Normalized School autocompletion for "west", limited to postsecondary schools and maximum 10 results [link](https://apimanagement.cbplatform.link/#routes/tester?preURL=https%3A%2F%2Fapi.careerbuilder.com%2F&postURL=core%2Fautocomplete%2Fnormalizedschools%3Fquery%3Dwest%26school_level%3Dpostsecondary%26limit%3D10&method=get&contentType=application%2Fjson&acceptType=application%2Fjson&version=1.0®ion=productionus&flow=client_credentials&userDid=&accountDid=&headers=&body=)** 167 | 168 | **Request** 169 | 170 | `https://www.api.careerbuilder.com/core/autocomplete/normalizedschools?query=west&school_level=postsecondary&limit=10` 171 | 172 | ## Sample Response 173 | 174 | ```json 175 | { 176 | "data": { 177 | "results": [ 178 | { 179 | "suggestion": "Western Michigan University", 180 | "id": "53bff579e4b04710d09fe614", 181 | "school_level": "POSTSECONDARY" 182 | }, 183 | { 184 | "suggestion": "West Virginia University", 185 | "id": "53bff579e4b04710d09fe5e8", 186 | "school_level": "POSTSECONDARY" 187 | }, 188 | { 189 | "suggestion": "Western Illinois University", 190 | "id": "53bff579e4b04710d09fe60e", 191 | "school_level": "POSTSECONDARY" 192 | }, 193 | { 194 | "suggestion": "Western Washington University", 195 | "id": "53bff579e4b04710d09fe634", 196 | "school_level": "POSTSECONDARY" 197 | }, 198 | { 199 | "suggestion": "Western Kentucky University", 200 | "id": "53bff579e4b04710d09fe613", 201 | "school_level": "POSTSECONDARY" 202 | }, 203 | { 204 | "suggestion": "Western Governors University", 205 | "id": "53bff579e4b04710d09fe60c", 206 | "school_level": "POSTSECONDARY" 207 | }, 208 | { 209 | "suggestion": "West Chester University of Pennsylvania", 210 | "id": "53bff579e4b04710d09fe5b4", 211 | "school_level": "POSTSECONDARY" 212 | }, 213 | { 214 | "suggestion": "Western Carolina University", 215 | "id": "53bff579e4b04710d09fe603", 216 | "school_level": "POSTSECONDARY" 217 | }, 218 | { 219 | "suggestion": "Westchester Community College", 220 | "id": "53bff579e4b04710d09fe5f2", 221 | "school_level": "POSTSECONDARY" 222 | }, 223 | { 224 | "suggestion": "Westwood College", 225 | "id": "53bff579e4b04710d09fe656", 226 | "school_level": "POSTSECONDARY" 227 | } 228 | ], 229 | "data_version": "2018-03-29" 230 | } 231 | } 232 | ``` 233 | 234 | **Multiple taxonomies request (carotenev3, school_norm) [link](https://apimanagement.cbplatform.link/?#routes/tester?preURL=https%3A%2F%2Fwwwtest.api.careerbuilder.com%2F&postURL=%2Fcore%2Fautocomplete%2Ftaxonomies&method=post&contentType=application%2Fjson&acceptType=application%2Fjson&version=1.0®ion=staging&flow=client_credentials&userDid=&accountDid=&headers=&body={+%0D%0A+++%22query%22%3A%22java%22%2C%0D%0A+++%22limit%22%3A3%2C%0D%0A+++%22taxonomies%22+%3A+[%22carotenev3%22%2C+%22school_norm%22]%0D%0A})** 235 | 236 | **Request** 237 | 238 | ```json 239 | { 240 | "query":"java", 241 | "limit":3, 242 | "taxonomies" : ["carotenev3", "school_norm"] 243 | } 244 | ``` 245 | ## Sample Response 246 | 247 | ```json 248 | { 249 | "data": { 250 | "results": [ 251 | { 252 | "results": [ 253 | { 254 | "suggestion": "Java Analyst", 255 | "id": "15.11674" 256 | }, 257 | { 258 | "suggestion": "Java Architect", 259 | "id": "15.128" 260 | }, 261 | { 262 | "suggestion": "Java Developer", 263 | "id": "15.2" 264 | } 265 | ], 266 | "taxonomy": "CAROTENEV3" 267 | }, 268 | { 269 | "results": [ 270 | { 271 | "suggestion": "Jawaharlal Nehru Technological University", 272 | "id": "53bff579e4b04710d09fb35f", 273 | "school_level": "POSTSECONDARY" 274 | }, 275 | { 276 | "suggestion": "Jazan University", 277 | "id": "53bff579e4b04710d09fb36f", 278 | "school_level": "POSTSECONDARY" 279 | } 280 | ], 281 | "data_version": "2018-03-29", 282 | "taxonomy": "SCHOOL_NORM" 283 | } 284 | ] 285 | } 286 | } 287 | ``` 288 | 289 | ## Versioning 290 | The current API version is 1.0. API version must be specified in the Accept header, e.g. ```application/json;version=1.0```. 291 | 292 | The data version is dependent on the requested taxonomy. Normalized Company, Major, and School taxonomies are unversioned and subject to change over time; the service will always use the latest version of data available. Carotene, NAICS, ONet, and Skills taxonomies are strongly versioned; a version of any of these taxonomies will never change throughout its lifetime. 293 | 294 | Our general versioning strategy is available [here](/Versioning.md). 295 | -------------------------------------------------------------------------------- /NextJob.md: -------------------------------------------------------------------------------- 1 | Next Job 2 | ================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | 13 | ## Summary 14 | 15 | The Next Job service returns common next jobs for a given carotene ID. For example, Administrative 16 | Assistant and Office Manager are common next jobs for Receptionists. Additionally it returns carotene description and the 17 | set of skills associated with the requested carotene ID, as well as the skills the carotene ID has 18 | in common with its next jobs and the missing skills a person should acquire to pursue the next job. 19 | Moreover, for each job we provide active jobs count based on location passed to the endpoint. 20 | Salary will be provided based on the following criteria:: 21 | ** if postal_code or cbsa_code is provided we will return for specific area 22 | ** if not we will provide nation wide data 23 | You can get this salary per hour or per year. 24 | 25 | hostsite is now supported. 26 | "OG" or "US" are accepeted. Allowing to target a CareerBuilder hostsite. 27 | Defaulted to US if not provided. 28 | 29 | 30 | 31 | The Next Job service is available at `/core/careerpath/nextjob`. 32 | 33 | ## Request Structure 34 | 35 | Requests consist of: 36 | 37 | | Field name | Type |Required| 38 | |:------------------|:-------|:-------| 39 | |`carotene_id` | string | Y | 40 | |`carotene_version` | string | Y | 41 | |`salary_period` | string | Y | // "HOUR" OR "YEAR" 42 | |`cbsa_code` | string | N | 43 | |`postal_code` | string | N | 44 | |`locality` | string | N | 45 | |`admin_area` | string | N | 46 | |`hostsite` | string | N | // "US" OR "OG" 47 | |`country` | string | N | 48 | 49 | Example cURL request with cbsa_code: 50 | 51 | ``` 52 | curl -X POST \ 53 | https://api.careerbuilder.com/core/careerpath/nextjob \ 54 | -H 'Accept: application/json;version=2.0' \ 55 | -H 'Authorization: ' \ 56 | -H 'Content-Type: application/json' \ 57 | -d '{ 58 | "carotene_id": "11.0", 59 | "carotene_version": "carotenev3", 60 | "salary_period": "YEAR", 61 | "cbsa_code": "77000", 62 | "locality": "Chicago", 63 | "admin_area": "IL" 64 | }' 65 | ``` 66 | 67 | Example cURL request with postal_code: 68 | 69 | ``` 70 | curl -X POST \ 71 | https://api.careerbuilder.com/core/careerpath/nextjob \ 72 | -H 'Accept: application/json;version=2.0' \ 73 | -H 'Authorization: ' \ 74 | -H 'Content-Type: application/json' \ 75 | -d '{ 76 | "carotene_id": "11.0", 77 | "carotene_version": "carotenev3", 78 | "salary_period": "YEAR", 79 | "postal_code": "60601", 80 | "locality": "Chicago", 81 | "admin_area": "IL" 82 | }' 83 | ``` 84 | 85 | Note that currently only Carotene v3 is supported. See the documentation for [Job Title service](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/JobTitle.md) 86 | for more information about carotene classification and carotene IDs. 87 | 88 | ## Response Structure 89 | 90 | The response consist of a `carotene_id`, `carotene_title`, `carotene_description`, `salary`,`active_job_count` and list of `skills` for the requested 91 | `carotene_id`. Each item in the `skills` list contains `term`, `id`, `type` strings, and `description` 92 | strings as well as list of links to relevant videos. The `next_jobs` sections is 93 | a list consisting of objects containing a `carotene_id`, `carotene_title`, `carotene_description`, `confidence`, `salary`,`active_job_count` and string for the next job as well as a list of `common_skills` and list of `missing_skills`. 94 | 95 | ```json 96 | { 97 | "data": { 98 | "carotene_id": "11.0", 99 | "carotene_title": "sales manager (management)", 100 | "carotene_description": "Plan, direct, or coordinate the actual distribution or movement of a product or service to the customer. Coordinate sales distribution by establishing sales territories, quotas, and goals and establish training programs for sales representatives. Analyze sales statistics gathered by staff to determine sales potential and inventory requirements and monitor the preferences of customers.", 101 | "salary": { 102 | "currency": "USD", 103 | "percentile_10": 21870.0, 104 | "percentile_25": 30660.0, 105 | "percentile_75": 48340.0, 106 | "percentile_90": 59100.0, 107 | "median": 38500.0, 108 | "mean": 39690.0, 109 | "employment_per_thousand_jobs": 12.311, 110 | "wage_percent_relative_standard_error": 1.2, 111 | "salary_period": "YEAR" 112 | }, 113 | "active_job_count": 567, 114 | "skills": [ 115 | { 116 | "term": "manage sale team", 117 | "id": "KS123X777H5WFNXQ6BPM", 118 | "type": "Professional Skill", 119 | "description": "Sales are activities related to selling or the number of goods or services sold in a given time period. The seller or the provider of the goods or services complete a sale in response to an acquisition, appropriation, requisition or a direct interaction with the buyer at the point of sale.", 120 | "videos": [ 121 | { 122 | "url": "https://www.youtube.com/watch?v=Qnd8j8rxEB0", 123 | "video_title": "Tips to Build and Manage an Excellent Sales Team" 124 | }, 125 | { 126 | "url": "https://www.youtube.com/watch?v=dfzozk7eGF4", 127 | "video_title": "3 Key Skills for Effective Sales Management" 128 | } 129 | ] 130 | }, 131 | { 132 | "term": "business development", 133 | "id": "KS1212B6QR5SK1LSD4S4", 134 | "description": "Business development entails tasks and processes to develop and implement growth opportunities within and between organizations. It is a subset of the fields of business, commerce and organizational theory.", 135 | "videos": [ 136 | { 137 | "url": "https://www.youtube.com/watch?v=i5Xwy-XBVgk", 138 | "video_title": "The 10 Keys to Business Development" 139 | }, 140 | { 141 | "url": "https://www.youtube.com/watch?v=PEM1BY-cJN8", 142 | "video_title": "Breakfast with Bakke Norman - SBA Financing presented by Jeremy Price" 143 | } 144 | ] 145 | } 146 | ], 147 | "next_jobs": [ 148 | { 149 | "carotene_id": "11.13", 150 | "carotene_title": "business development manager (management)", 151 | "carotene_description": "Plan, direct, or coordinate marketing policies and programs, such as determining the demand for products and services offered by a firm and its competitors, and identify potential customers. Develop pricing strategies with the goal of maximizing the firm's profits or share of the market while ensuring the firm's customers are satisfied. Oversee product development or monitor trends that indicate the need for new products and services.", 152 | "confidence": 0.016686638076838227, 153 | "salary": { 154 | "currency": "USD", 155 | "percentile_10": 21870.0, 156 | "percentile_25": 30660.0, 157 | "percentile_75": 48340.0, 158 | "percentile_90": 59100.0, 159 | "median": 38500.0, 160 | "mean": 39690.0, 161 | "employment_per_thousand_jobs": 12.311, 162 | "wage_percent_relative_standard_error": 1.2, 163 | "salary_period": "YEAR" 164 | }, 165 | "active_job_count": 128, 166 | "common_skills": [ 167 | { 168 | "term": "business development", 169 | "id": "KS1212B6QR5SK1LSD4S4", 170 | "type": "Professional Skill", 171 | "description": "Business development entails tasks and processes to develop and implement growth opportunities within and between organizations. It is a subset of the fields of business, commerce and organizational theory.", 172 | "videos": [ 173 | { 174 | "url": "https://www.youtube.com/watch?v=i5Xwy-XBVgk", 175 | "video_title": "The 10 Keys to Business Development" 176 | }, 177 | { 178 | "url": "https://www.youtube.com/watch?v=OB2t8UvXMWU", 179 | "video_title": "Creating a Sales and Business Development Strategy - Entrepreneurship 101 2009/10" 180 | } 181 | ] 182 | }, 183 | { 184 | "term": "negotiation", 185 | "id": "KS126X663B21NB77ZHSP", 186 | "type": "Professional Skill", 187 | "description": "Negotiation comes from the Latin neg (no) and otsia (leisure) referring to businessmen who, unlike the patricians, had no leisure time in their industriousness; it held the meaning of business (le négoce in French) until the 17th century when it took on the diplomatic connotation as a dialogue between two or more people or parties intended to reach a beneficial outcome over one or more issues where a conflict exists with respect to at least one of these issues. Thus, negotiation is a process of combining divergent positions into a joint agreement under a decision rule of unanimity.", 188 | "videos": [ 189 | { 190 | "url": "https://www.youtube.com/watch?v=oy0MD2nsZVs", 191 | "video_title": "Negotiation Skills Top 10 Tips" 192 | }, 193 | { 194 | "url": "https://www.youtube.com/watch?v=rCmvMDrCWjs", 195 | "video_title": "Conducting Effective Negotiations" 196 | } 197 | ] 198 | } 199 | ], 200 | "missing_skills": [ 201 | { 202 | "term": "meet sales objectives", 203 | "id": "KS123X777H5WFNXQ6BPM", 204 | "type": "Professional Skill", 205 | "description": "Sales are activities related to selling or the number of goods or services sold in a given time period. The seller or the provider of the goods or services complete a sale in response to an acquisition, appropriation, requisition or a direct interaction with the buyer at the point of sale.", 206 | "videos": [] 207 | }, 208 | { 209 | "term": "ensure customer satisfaction", 210 | "id": "KS122LN6CLX3P61KWSP2", 211 | "type": "Professional Skill", 212 | "description": "Customer satisfaction (often abbreviated as CSAT, more correctly CSat) is a term frequently used in marketing. It is a measure of how products and services supplied by a company meet or surpass customer expectation.", 213 | "videos": [ 214 | { 215 | "url": "https://www.youtube.com/watch?v=LbIB4KW9aZY", 216 | "video_title": "How To Serve Customers Better To Ensure Customer Satisfaction" 217 | }, 218 | { 219 | "url": "https://www.youtube.com/watch?v=XK3cNcuvuMs", 220 | "video_title": "5 Steps To Improve Customer Satisfaction" 221 | } 222 | ] 223 | } 224 | ] 225 | } 226 | ] 227 | } 228 | } 229 | ``` 230 | 231 | ## Versioning 232 | The current version of the service is 2.0. 233 | 234 | Version must be specified in the Accept header. E.g. `application/json;version=2.0`. 235 | 236 | Our general versioning strategy is available [here](/Versioning.md). 237 | -------------------------------------------------------------------------------- /SemanticSearchV2.md: -------------------------------------------------------------------------------- 1 | Semantic Search API V2 2 | ===================== 3 | 4 | The semantic search API supports two endpoints: /query and /document. 5 | The /query endpoint interprets and provides related entities for queries. 6 | The /document endpoint parses a document, either a job or resume, and returns the most relevant semantic entities. 7 | 8 | # Table of Contents 9 | _____________ 10 | 11 | ## Query Endpoint 12 | 13 | - [Query Description](#query-description) 14 | 15 | - [Query Request Information](#query-request-information) 16 | 17 | - [Query Response](#query-response) 18 | 19 | ## Document Endpoint 20 | 21 | - [Document Description](#document-description) 22 | 23 | - [Document Request Information](#document-request-information) 24 | 25 | - [Document Response](#document-response) 26 | 27 | # Query Description 28 | 29 | Interprets the meaning of a user's query. Used to parse a query into the intended phrases, to identify the type of entities being searched for (job title, skill, company, location, etc.), and to identify the most related other phrases/entities that help better represent the intended query. This service also applies stored user overrides to queries when user parameters are supplied in conjunction with the Semantic Overrides API. 30 | 31 | 32 | # Query Request Information 33 | 34 | 35 | HTTP method: GET or POST 36 | Parameters (query/form): 37 | - query (required) : query to parse and from which to infer meaning. 38 | - language (optional) : two letter language code followed by underscore, followed by two letter country code. Determines the language in which enrichments are returned. Required to use personalized overrides. Defaults to en_us. Currently, allowed values are en_us, en_gb, fr_fr, de_de, and nl_nl. 39 | - user_id (optional) : user id for which to look up personalized overrides. Defaults to null. 40 | - relationships_threshold : the mimimum weight of a relationship entity to be added as enrichments. Can be used to prune the result size. Defaults to 0.5. Allowed values are any number between 0 and 1. 41 | 42 | Example 2.0 request: 43 | ``` 44 | HTTP GET 45 | Accept: application/json;version=2.0 46 | https://api.careerbuilder.com/core/semanticsearch/query?query=registered%20nurse&language=en_us&user_id=U1234 47 | ``` 48 | 49 | # Query Response 50 | 51 | The query response is divided into two parts. First is the parsed_input node, which gives information about parsing of extracted keywords in the query (this node is missing in the document response). 52 | Second is the extracted_keywords node, which gives the type and related entities of each extracted keyword. Enrichments can be overridden to be returned with a selected=true flag for a given user_id through the Overrides API. 53 | 54 | 2.0 response: 55 | ``` 56 | { 57 | "data": { 58 | "parsed_input": { 59 | "input": "keyword", 60 | "parsed": "{extracted keyword}", 61 | "raw_parsed_input": "{keyword}", 62 | "input_to_extracted_keywords": { 63 | "keyword": "extracted keyword" 64 | }, 65 | "parsed_fragments": ["extracted keyword"] 66 | }, 67 | "extracted_keywords": [{ 68 | "name": "extracted keyword", 69 | "weight": 100.0, 70 | "type": "entity type", 71 | "relationships": { 72 | "job_titles": [{ 73 | "name": "extracted keyword job title", 74 | "id": "1", 75 | "selected": true, 76 | "weight": 1.0 77 | }], 78 | "occupations": [{ 79 | "name": "extracted keyword occupation", 80 | "id": "99-9999.99", 81 | "weight": 1.0 82 | }], 83 | "related_keywords": [{ 84 | "name": "extracted keyword related keyword", 85 | "weight": 1.0 86 | }], 87 | "related_keywords_recruiter": [{ 88 | "name": "extracted keyword related keyword", 89 | "weight": 1.0 90 | }], 91 | "related_keywords_jobseeker": [{ 92 | "name": "extracted keyword related keyword", 93 | "weight": 1.0 94 | }], 95 | "skills": [{ 96 | "name": "extracted keyword skill", 97 | "selected": true, 98 | "weight": 1.0 99 | }], 100 | "raw_job_titles_recruiter": [{ 101 | "name": "extracted keyword job title", 102 | "weight": 1.0 103 | }], 104 | "raw_job_titles_jobseeker": [{ 105 | "name": "extracted keyword job title", 106 | "weight": 1.0 107 | }], 108 | "job_level": [{ 109 | "name": "extracted keyword job level", 110 | "weight": 1.0 111 | }], 112 | "text_kernel_related_keywords": [{ 113 | "name": "extracted keyword Text Kernel related keyword", 114 | "weight": 1.0 115 | }] 116 | } 117 | }], 118 | "versions": { 119 | "interesting_keywords": "InterestingTermsV2", 120 | "job_level": "JobLevel", 121 | "job_titles": "CaroteneV3", 122 | "occupations": "ONet17", 123 | "raw_job_titles_jobseeker": "RawJobTitlesJobSeekerV1", 124 | "raw_job_titles_recruiter": "RawJobTitlesRecruiterV1", 125 | "related_keywords": "RelatedSearchTermsV1", 126 | "related_keywords_jobseeker": "RelatedSearchTermsJobseekerV1", 127 | "related_keywords_recruiter": "RelatedSearchTermsRecruiterV1", 128 | "skills": "SkillsV4", 129 | "text_kernel_related_keywords": "TextKernelRelatedSearchTerms", 130 | "custom_keywords": "CustomKeywords" 131 | } 132 | } 133 | } 134 | ``` 135 | 136 | # Document Description 137 | 138 | Used to parse a job or resume into its most important features and to represent these as a prioritized list of features that can be used to form a matching query. 139 | 140 | # Document Request Information 141 | 142 | HTTP method: POST. 143 | 144 | Parameters: 145 | - language (optional) : two letter language code followed by underscore, followed by two letter country code. Determines the language in which enrichments are returned. Required to use personalized overrides. Defaults to en_us. Currently, allowed values are en_us, en_gb, fr_fr, de_de, and nl_nl. 146 | - user_id (optional) : user id for which to look up personalized overrides. Defaults to null. 147 | - relationships_threshold : the mimimum weight for a relationship entry to be added as enrichment. Can be used to prune the result size. Defaults to 0.5. Allowed values are any number between 0 and 1. 148 | - document (required) : base64 encoded string of the document to be parsed. 149 | - type (required) : the type of the document. Acceptable values are "JOB" and "RESUME". 150 | - job_title (optional, only valid when type is JOB) : a pre-defined job title which overrides the job_title field extracted from a job document. Note that the job_title field will also be cleaned. 151 | - location (required, only valid when type is JOB): location for a job document, could be vacancy or company location. 152 | 153 | Example 2.0 request: 154 | ``` 155 | HTTP POST 156 | Accept: application/json;version=2.0 157 | https://api.careerbuilder.com/core/semanticsearch/document 158 | { 159 | "type": "JOB", 160 | "document": "SmF2YSBkZXZlbG9wZXIKCkNvbXBhbnk6IENhcmVlckJ1aWxkZXIKTG9jYXRpb246IEF0bGFudGEsIEdlb3JnaWEKCgpBcHBseSBub3chIFRoYW5rIHlvdSBmb3IgYXBwbHlpbmcuCg==", 161 | "location": "200 N LaSalle St, Chicago" 162 | "relationships_threshold": "0.9" 163 | } 164 | ``` 165 | 166 | # Document Response 167 | 168 | The document response includes the following parts. First is the `parsed_input` node which contains information on all extracted keywords and phrases. Next is the `semantic_keywords` node, which gives the name, type and relationships of all extracted phrases. The response may also include additional objects such as `job_titles`, `location`, `geographies`. These objects are derived from parsing the job or resume document, and may not appear when the supplied document lacks corresponding information. 169 | 170 | - data 171 | - parsed_input 172 | - input (list): comma-separated list of extracted keywords and phrases 173 | - parsed_fragments (list): input as list of strings 174 | - input_to_extracted_keywords (map): mapping extracted strings to canonical strings 175 | - semantic_keywords (list) 176 | - name (string): canonical name 177 | - weight (float): estimated weight (0-100) 178 | - type (string): skill, job_title, keyword, company, school, location 179 | - relationships (map of strings): 180 | - occupations (for type: job_title, skill, company, keyword) 181 | - related_keywords (for type: job_title, skill, company, keyword) 182 | - skills (for type: job_title, skill, company, keyword) 183 | - job_titles (for type: job_title, skill, company, keyword) 184 | - job_level (for type: job_title, skill, company, keyword) 185 | - education_level (for type:school) 186 | - location: possible fields are address, city, country, region, state, zip. 187 | 188 | *(The following fields are only available when requesting a job document.)* 189 | - company_geographies (list): contains geography objects. 190 | - contract_type (string): whether the contract is permanent, temporary, internship, etc. 191 | - education_level (string): minimum education level required by the job posting. 192 | - employment_level (string): whether the job is full-time, part-time, etc. 193 | - experience_level: possible fields are level, min_years, max_years. 194 | - job_titles (list): each object contains name, source, confidence, id. 195 | - job_level (string): experience, or seniority level of the job posting. 196 | - language_skills (list): contains a list of language skills, each language is a string type. 197 | 198 | *(The following fields are only available when requesting a resume document.)* 199 | - candidate_experience: possible fields are experience_months, experience_months_by_job_category (list) 200 | - geographies (list): contains geography objects. 201 | - highest_education_level (string): the highest education achieved. 202 | - most_recent_employment_level (string): whether the latest job is fulltime, parttime, etc. 203 | 204 | 2.0 response: 205 | ``` 206 | { 207 | "data" : { 208 | "semantic_keywords" : [ 209 | { 210 | "name" : "java developer", 211 | "relationships" : { 212 | "skills" : [ 213 | { 214 | "weight" : 1, 215 | "name" : "Java (Programming Language)", 216 | "id" : "KS120076FGP5WGWYMP0F" 217 | }, 218 | { 219 | "name" : "Hibernate (Java)", 220 | "id" : "KS124PR62MV42B5C9S9F", 221 | "weight" : 0.93154 222 | }, 223 | { 224 | "id" : "KS123KG6DL8N3D5ZW036", 225 | "name" : "Java Platform Enterprise Edition (J2EE)", 226 | "weight" : 0.92962 227 | } 228 | ], 229 | "job_titles" : [ 230 | { 231 | "id" : "15.2", 232 | "name" : "Java Developer", 233 | "weight" : 1 234 | } 235 | ], 236 | "job_level" : [ 237 | { 238 | "name" : "Experienced (non-Manager)", 239 | "id" : "3", 240 | "weight" : 1 241 | } 242 | ], 243 | "occupations" : [], 244 | "related_keywords" : [] 245 | }, 246 | "type" : "job_title", 247 | "weight" : 100 248 | }, 249 | { 250 | "name" : "careerbuilder", 251 | "type" : "company", 252 | "weight" : 100 253 | "relationships" : {}, 254 | }, 255 | ... 256 | ], 257 | "location":{ 258 | "address" : "Peachtree pkwy, Norcross, Georgia, United States", 259 | "city" : "Norcross", 260 | "region" : "Georgia", 261 | "country" : "United States" 262 | }, 263 | "job_titles" : [ 264 | { 265 | "name" : "Client Services Manager", 266 | "source" : "carotenev3.1", 267 | "confidence" : 1, 268 | "id" : "11.114" 269 | }, 270 | ... 271 | ], 272 | "experience_level" : { 273 | "min_years" : 10, 274 | "max_years" : 0 275 | }, 276 | "company_geographies" : [ 277 | { 278 | "admin_areas" : [ 279 | { 280 | "long_name" : "Georgia", 281 | "short_name" : "GA", 282 | "level" : 1 283 | }, 284 | { 285 | "long_name" : "Gwinnett County", 286 | "short_name" : "Gwinnett County", 287 | "level": 2 288 | } 289 | ], 290 | "country" : "United States", 291 | "country_code" : "US", 292 | "formatted_address" : "Norcross, GA, USA", 293 | "latitude" : 33.9412127, 294 | "longitude" : -84.2135309, 295 | "locality" : "Norcross", 296 | "location_type" : "LOCALITY", 297 | "place_id" : "ChIJqTKlbTih9YgRVjJ2xmfcfJQ", 298 | "viewport" : { 299 | "northeast" : { 300 | "lat" : 33.9685209, 301 | "lng" : -84.173478 302 | }, 303 | "southwest" : { 304 | "lat" : 33.920772, 305 | "lng" : -84.23084109999999 306 | }, 307 | "suggested_radius_miles" : 2.3295469101154485 308 | }, 309 | "metropolitan_statistical_area" : { 310 | "title" : "Atlanta-Sandy Springs-Roswell, GA", 311 | "code" : 12060 312 | }, 313 | "designated_market_areas" : [ 314 | "Atlanta, GA" 315 | ], 316 | "partial_match" : false 317 | } 318 | ], 319 | "education_level" : "BACHELORS_DEGREE", 320 | "employment_level" : "FULL_TIME", 321 | "contract_type" : "PERMANENT", 322 | "job_level" : "ENTRY_LEVEL", 323 | "language_skills" : ["EN", ...], 324 | "candidate_experience" : { 325 | "experience_months" : 8, 326 | "experience_months_by_job_category" : [ 327 | { 328 | "job_category_code" : "27", 329 | "job_category_description" : "Arts, Design, Entertainment, Sports, and Media Occupations", 330 | "months" : 8 331 | }, 332 | ... 333 | ] 334 | }, 335 | "geographies" : [*(same as company_geographies)*], 336 | "highest_education_level" : "Master's Degree", 337 | "most_recent_employment_level" : "FULL_TIME" 338 | } 339 | } 340 | ``` 341 | -------------------------------------------------------------------------------- /JobParseAndNormalize.md: -------------------------------------------------------------------------------- 1 | Job Parse and Normalize API 2 | ==================== 3 | 4 | #### Table of Contents 5 | _______ 6 | 7 | - [Summary](#summary) 8 | - [Request structure](#request-structure) 9 | - [Response structure](#response-structure) 10 | - [Versioning](#versioning) 11 | 12 | ## Summary 13 | 14 | The Job Parse and Normalize (JPAN) service parses a Base64-encoded job posting and further enriches the parsed data with the following normalizations and classifications. 15 | 16 | #### Available Enrichments: 17 | - __Job Title Classifications__ 18 | - __[Carotene](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/JobTitle.md)__ (optional) 19 | - __[ONET](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/JobTitle.md)__ (optional) 20 | - __[Normalized Company](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/CompanyNormalization.md)__ (optional) - Normalized company data including name, website, etc. 21 | - __Skills Extraction__ 22 | - __[CareerBuilder Skills Extraction](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/Skills.md)__ (optional) - When `skillsv8` is requested as a `desired_enrichment`, the service will enrich the parsed job data using the CareerBuilder Skills API. 23 | - __Language Skills__ 24 | - __[Geocoding](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/Geocoding.md)__ (optional) - Location normalization for both company and job locations 25 | - __[Job Level](https://github.com/cbdr/DataScienceAPIDocumentation/blob/master/JobLevel.md)__ (optional) - Experience, or seniority level of the job posting 26 | - __Summary__ (optional) - Summary of the job created by LLM 27 | 28 | Enrichments marked as __(optional)__ must be requested using the `desired_enrichments` parameter, as they require additional calls to other services. For example, a client who only needs Job Title and Skills classifications could structure a Job Parse and Normalize request that would only retrieve these classifications. This parameter is documented in further detail below. 29 | 30 | The service is located at https://api.careerbuilder.com/core/parsing/normalizedjob. As usual, you will need OAuth core credentials to use this service. (*If you do not have these, please go [here](http://apitester.cbplatform.link/credentials) or email PlatformSoftware@careerbuilder.com to request core credentials.*) 31 | 32 | ## Request Structure 33 | 34 | This service supports the HTTP GET and POST methods. Because Base64-encoded documents can be quite large, POST is encouraged for production use. 35 | 36 | The following parameters may be supplied in the query string (for HTTP GET) or form body (for HTTP POST): 37 | 38 | * **document** (Required) -- A .doc, .docx, .pdf, .rtf, .txt, .odt, or .wps document given in a BASE64 encoded string. 39 | 40 | * **url** (Optional) -- When parsing html, the Job Parser has custom parsing rules for [certain domains](#domains-with-custom-parsing-rules) that can improve the quality of the parse. This field allows users who are sending html to specify the url of the document and thereby improve parsing quality for domains which have custom parsing rules. Users including this field should use the full url of the document. 41 | 42 | * **job_title** (Optional) -- The job title for the document. _**Required if desired_enrichments JOB_LEVEL is requested**_ 43 | 44 | * **language** (Optional) -- The language of the document, specified using language codes (e.g., "en" for English, "fr" for French). 45 | 46 | * **Company Information Attributes** 47 | * **company_name** (Optional): The name of the company associated with the job or vacancy. _**Required if Enrichment.COMPANY_NORM is requested.**_ 48 | * **company_address** (Optional): The street address of the company. 49 | * **company_locality** (Optional): The locality or city where the company is located. 50 | * **company_admin_area** (Optional): The administrative area or region (e.g., state or province) where the company is located. 51 | * **company_postal_code** (Optional): The postal code of the company's address. 52 | * **company_country** (String): The country where the company is located. 53 | 54 | * **Vacancy Location Attributes** 55 | * **vacancy_address** (Optional): The specific street address where the vacancy is based, if different from the company's main address. 56 | * **vacancy_locality** (Optional): The locality or city where the vacancy is located. 57 | * **vacancy_admin_area** (Optional): The administrative area or region of the vacancy location. 58 | * **vacancy_postal_code** (Optional): The postal code for the vacancy's address. 59 | * **vacancy_country** (Optional): The country where the vacancy is located. 60 | 61 | **If desired_enrichments GEOCODING is requested, at least one location-related attribute (either in the company or vacancy section) must be provided.** 62 | 63 | * **desired_enrichments** (Required) -- A comma-separated list, without spaces, of the desired normalization calls to perform on the results of the job parsing operation. 64 | 65 | 66 | This list of possible values for **desired_enrichments** and the enrichments they correspond to are as follows: 67 | 68 | |desired_enrichments | Enrichment(s) | 69 | | --- | --- | 70 | | `company_norm` | Normalized Company Name | 71 | | `geocoding` | Company Geography, Job Geography | 72 | | `job_level` | Job Level | 73 | | `job_title_carotene` | Carotene Job Title Classifications | 74 | | `job_title_onet` | ONET Job Title Classifications | 75 | | `skillsv8` | Careerbuilder Skills V8 Extraction | 76 | | `summary` | Summary from the job created by LLM| 77 | 78 | For example, a request with a desired_enrichments value equal to `job_level,skillsv5,job_title_onet,company_norm` would receive job level classifications, skills V5 extractions, ONet job title classifications, and company normalizations. The API does not currently allow callers to request only certain versions of a classification service. The value `none` must be supplied to return none of the optional enrichments. 79 | 80 | 81 | 82 | ## Response Structure 83 | Salary information is coming from the legacy Monster Salary parsing service. Please note that the "parsed" node will not be present if we are unable to find any salary information. 84 | 85 | ``` 86 | { 87 | "data": { 88 | "parsed": { 89 | "salary": { 90 | "from": "35000", 91 | "to": "38000", 92 | "time_scale": "ANNUAL", 93 | "currency": "USD" 94 | } 95 | }, 96 | "normalized": { 97 | "normalized_company": { 98 | "normalized_companies": [ 99 | { 100 | "confidence": "float", 101 | "normalized_name": "string", 102 | "id": "string", 103 | "naics_code": "string", 104 | "naics_description": "string", 105 | "duns_number": "string", 106 | "website": "string", 107 | "country": "string", 108 | "state": "string", 109 | "postal_code": "string", 110 | "city": "string", 111 | "address": "string", 112 | "company_size": "integer", 113 | "is_staffing_company": "boolean" 114 | } 115 | ], 116 | "master_company": { 117 | "confidence": "float", 118 | "normalized_name": "string", 119 | "id": "string", 120 | "naics_code": "string", 121 | "naics_description": "string", 122 | "duns_number": "string", 123 | "website": "string", 124 | "country": "string", 125 | "state": "string", 126 | "postal_code": "string", 127 | "city": "string", 128 | "address": "string", 129 | "company_size": "integer", 130 | "is_staffing_company": "boolean" 131 | }, 132 | "data_version": "string" 133 | }, 134 | "skills": { 135 | "8.0": [ 136 | { 137 | "type": "string", 138 | "skilldid": "string", 139 | "normalized_term": "string", 140 | "extracted_term": "string", 141 | "confidence": "float" 142 | } 143 | ] 144 | }, 145 | "summary": "string", 146 | "company_geographies": { 147 | "2.0": [ 148 | { 149 | "admin_areas": [ 150 | { 151 | "long_name": "string", 152 | "short_name": "string", 153 | "level": "integer" 154 | } 155 | ], 156 | "country": "string", 157 | "country_code": "string", 158 | "formatted_address": "string", 159 | "latitude": "float", 160 | "locality": "string", 161 | "location_type": "string", 162 | "longitude": "float", 163 | "partial_match": "boolean", 164 | "place_id": "string", 165 | "postal_code": "string", 166 | "street_address": "string", 167 | "metropolitan_statistical_area": { 168 | "title": "string", 169 | "code": "integer" 170 | }, 171 | "viewport": { 172 | "northeast": { 173 | "lat": "float", 174 | "lng": "float" 175 | }, 176 | "southwest": { 177 | "lat": "float", 178 | "lng": "float" 179 | }, 180 | "suggested_radius_miles": "float" 181 | }, 182 | "designated_market_areas": ["string"] 183 | } 184 | ] 185 | }, 186 | "job_geographies": { 187 | "2.0": [ 188 | { 189 | "admin_areas": [ 190 | { 191 | "long_name": "string", 192 | "short_name": "string", 193 | "level": "integer" 194 | } 195 | ], 196 | "country": "string", 197 | "country_code": "string", 198 | "formatted_address": "string", 199 | "latitude": "float", 200 | "locality": "string", 201 | "location_type": "string", 202 | "longitude": "float", 203 | "partial_match": "boolean", 204 | "place_id": "string", 205 | "postal_code": "string", 206 | "street_address": "string", 207 | "metropolitan_statistical_area": { 208 | "title": "string", 209 | "code": "integer" 210 | }, 211 | "viewport": { 212 | "northeast": { 213 | "lat": "float", 214 | "lng": "float" 215 | }, 216 | "southwest": { 217 | "lat": "float", 218 | "lng": "float" 219 | }, 220 | "suggested_radius_miles": "float" 221 | }, 222 | "designated_market_areas": ["string"] 223 | } 224 | ] 225 | }, 226 | "document_language": "string" 227 | }, 228 | "description": "string", 229 | "score": "float", 230 | "score_bucket": "string", 231 | "quality_check_list": { 232 | "is_spam": "boolean", 233 | "is_for_multiple_roles": "boolean", 234 | "has_misleading_content": "boolean", 235 | "is_less_than400_characters": "boolean", 236 | "is_job_info_incomplete": "boolean", 237 | "does_title_not_match_description": "boolean", 238 | "poor_quality": { 239 | "is_poor_quality": "boolean", 240 | "reason": { 241 | "is_job_info_incomplete": "boolean", 242 | "does_title_not_match_desc": "boolean" 243 | } 244 | } 245 | }, 246 | "is_spam": "boolean" 247 | } 248 | } 249 | ``` 250 | Job score is based on the quality of the job title and description: 251 | 252 | 1. **Title Score (up to 50 points)**: 253 | - Must be under 100 characters. 254 | - Must be well-formatted (not fully capitalized and free of undesirable characters). 255 | - Must be properly classified with sufficient confidence. 256 | 257 | 2. **Description Score (up to 50 points)**: 258 | - Must include at least two sentences. 259 | - Length must be between 2500-5500 characters. 260 | - Must meet formatting standards (not fully capitalized and free of undesirable characters). 261 | 262 | 3. **Total Score and Bucketing**: 263 | - The combined score ranges from 0 to 100. 264 | - Categorized into buckets based on score: 265 | - `VERY_LOW`: 0 points or flagged as spam 266 | - `LOW`: 1-30 points 267 | - `MEDIUM`: 31-70 points 268 | - `GOOD`: 71-100 points 269 | 270 | This scoring method evaluates both the title and description to determine overall job quality. 271 | 272 | 273 | ## Domains With Custom Parsing Rules 274 | 275 | Domains for which there are custom parsing rules include, but are not limited to: 276 | 277 | - indeed.com 278 | - truckdrivingjobs.com 279 | - glassdoor.com 280 | - care.com 281 | - snagajob.com 282 | - careerarc.com 283 | - monster.com 284 | - careerboard.com 285 | - jobserve.com 286 | - careersingear.com 287 | - dice.com 288 | - allnurses.com 289 | - resume-library.com 290 | - pure-jobs.com 291 | - thejobnetwork.com 292 | - mitalent.org 293 | - findatruckerjob.com 294 | - k12jobspot.com 295 | - disabledperson.com 296 | - jobing.com 297 | 298 | 299 | ## Versioning 300 | 301 | The data returned is unversioned. The current version is 1.0. We expect that each of our vendors return the same data for repeated calls, however we have not verified this systematically. We will occasionally update our vendors which may change the output. If we believe this change is significant we will communicate about it. However, customers will not be able to specify vendor versions. 302 | 303 | Our general versioning strategy is available [here](/Versioning.md). 304 | -------------------------------------------------------------------------------- /JobRecommendationService.md: -------------------------------------------------------------------------------- 1 | # Job Recommendation service 2 | 3 different model 3 | - [Platform](#job-Recommendation-service---Platform) 4 | - [Search](#jobsearch-endpoint) 5 | - [Wants](#job-recommendation-service---wants-endpoint) 6 | 7 | 8 | # Job Recommendation service - Platform 9 | # Contents 10 | 11 | - [Summary](#summary) 12 | - [Request structure](#request-structure) 13 | - [Response Structure](#response-structure) 14 | - [Versioning](#versioning) 15 | 16 | ---------------------------- 17 | # Summary 18 | 19 | Given a job ID and, optionally, a algorithm name and a host site, the Job Recommendation Service provides recommendations of relevant and similar jobs. 20 | 21 | ---------------------------- 22 | # Request structure 23 | The service supports `GET` and `POST` requests to: 24 | https://api.careerbuilder.com/consumer/recommendations/platform. 25 | 26 | OAUTH credentials are **required** and Documentation for CareerBuilder authentication is provided [here](https://apimanagement.cbplatform.link/#/oauth/faq) by the Platform Software team. 27 | 28 | The request parameters: 29 | 30 | | Param | Type | Required | Description | 31 | |----------|------|----------|-------------| 32 | | `jobID` | String | **True** | This needs to be a valid jobdid. 33 | | `hostSite` | String | **False** | Hostsite for source `jobID`. Currently supports US, UK, CA. Defaults to US if omitted 34 | | `personalizationAlgorithm` | String | **False** | Current supported algorithms are `gbr_only`(**default**), `gbr_programmatic`, `gbr_wfh`, `gbr_scale_ten`, `gbr_mix_a`, `gbr_mix_b`, `gbr_mix_b_ranked`, `flex_rec` 35 | 36 | 37 |   38 | ### Full Request Example 39 | 40 | ```json 41 | { 42 | "jobID": "J3T2QQ6CJCRBZ6JS46VS", 43 | "hostSite": "US", 44 | "personalizationAlgorithm": "gbr_only" 45 | } 46 | ``` 47 | ---------------------- 48 | # Response Structure 49 | 50 | All responses with an HTTP status of 200 will consist of a JSON object with a top-level "data" node containing a list of `records`, which is composed of recommended job metadata and its `score`. 51 | This example is showing an example of a programmatic job. 52 | If this not a programmatic job, "partner_id" will be set to 0 and "is_programmatic" to false 53 | 54 | Example response body: 55 | ```JSON 56 | { 57 | "data": { 58 | "records": [ 59 | { 60 | "city": "Chicago", 61 | "state": "IL", 62 | "date_posted": "2022-02-22T01:06:10.0000000Z", 63 | "company_name": "Button Chrysler Jeep Dodge Ram", 64 | "expire_date": "2022-03-21T23:59:59.0000000Z", 65 | "id": "J4R3CJ5X89FNYFPC25K", 66 | "has_quick_apply": false, 67 | "title": "Chrysler Certified Automotive Technician", 68 | "score": 0.7234, 69 | "location": "US-IL-Chicago", 70 | "job_details_url": "https://api.careerbuilder.com/v1/joblink?DID=J4R3CJ5X89FNYFPC25K&recid=TR659D6723C6384E9480F9A42071B1AB69", 71 | "description": " Chrysler Certified Automotive Technician ...", 72 | "pay": "$60,000 - $95,000/Year", 73 | "company_image_url": "", 74 | "partner_id": "PGMPTNR", 75 | "is_programmatic": true, 76 | "work_from_home": "true", 77 | "product_id": "JCPGM2" 78 | } 79 | ], 80 | "rec_id": "TR659D6723C6384E9480F9A42071B1AB69" 81 | } 82 | } 83 | ``` 84 | 85 |   86 | 87 | ----------- 88 | # Versioning 89 | The current API version is 1.0. The data returned from the service is unversioned. 90 | 91 | Our general versioning strategy is available [here](/Versioning.md). 92 | 93 | 94 | # Job Recommendation service - JobSearch Endpoint 95 | # Contents 96 | 97 | - [Summary](#summary) 98 | - [Request structure](#request-structure) 99 | - [Response Structure](#response-structure) 100 | 101 | ---------------------------- 102 | # Summary 103 | 104 | Given a carotene ID and, other params such as location, talentnetworkdidcsv and job did, the Job Recommendation Service provides recommendations of relevant and similar jobs. 105 | This service will trigger a jobsearch v4 based on the given parameters. 106 | ---------------------------- 107 | # Request structure 108 | The service supports `GET` and `POST` requests to: 109 | https://api.careerbuilder.com/consumer/jobs/recommendations. 110 | 111 | OAUTH credentials are **required** and Documentation for CareerBuilder authentication is provided [here](https://apimanagement.cbplatform.link/#/oauth/faq) by the Platform Software team. 112 | 113 | The request parameters: 114 | 115 | | Param | Type | Required | Description | 116 | |-----------------------|--------|------------|-----------------------------------------------------------------------| 117 | | `carotene_id` | String | **True** | This needs to be a valid carotene id. | 118 | | `host_site` | String | **True** | Hostsite for source `jobID`. Value is "US" | 119 | | `talentnetworkdidcsv` | String | **False** | This needs to be a valid talentnetworkdidcsv | 120 | | `job_did` | String | **False** | This needs to be a valid jobdid. | 121 | | `lat` | String | **False** | This needs to be a valid latitude. | 122 | | `lng` | String | **False** | This needs to be a valid longitude. | 123 | | `count_limit` | String | **False** | This needs to be a valid integer. count_limit range is from 1 to 100. | 124 | 125 |   126 | ### Full Request Example 127 | 128 | ```json 129 | { 130 | "carotene_id": "15.1272", 131 | "host_site": "US", 132 | "lat":32.81402, 133 | "lng":-96.94889, 134 | "count_limit": "10" 135 | } 136 | ``` 137 | ---------------------- 138 | # Response Structure 139 | 140 | Example response body: 141 | ```JSON 142 | { 143 | "total_pages": "2", 144 | "total_count": "14", 145 | "first_item_index": "1", 146 | "last_item_index": "10", 147 | "data": { 148 | "results": [ 149 | { 150 | "distance": "Nearby", 151 | "location": "TX - Irving", 152 | "hostsite": "US", 153 | "country_code": "US", 154 | "job_branding_icons": "", 155 | "id": "J3R7TZ6DFLZ4856891B", 156 | "job_title": "Big Data Developer", 157 | "display_city": "Irving", 158 | "admin_area_1": "TX", 159 | "latitude": "32.81402", 160 | "longitude": "-96.94889", 161 | "company_name": "Mindtree", 162 | "company_id": "", 163 | "discrete_field_1": "", 164 | "discrete_field_2": "", 165 | "discrete_field_3": "", 166 | "discrete_field_4": "", 167 | "discrete_field_5": "", 168 | "discrete_field_6": "", 169 | "discrete_field_7": "", 170 | "discrete_field_8": "", 171 | "discrete_field_9": "", 172 | "discrete_field_10": "", 173 | "job_details_url": "http://swarm.careerbuilder.com/v1/joblink?DID=J3R7TZ6DFLZ4856891B&TrackingID=306B089E-C58B-4A70-BFF8-9AA0FBE593A7&HostSite=us", 174 | "employment_type": "Full-Time", 175 | "employment_type_code": "JTFT", 176 | "education_required": "Not Specified", 177 | "education_required_code": "DRNS", 178 | "experience_required": "Not Specified", 179 | "experience_required_code": "", 180 | "external_client_key": "10440_3153205202", 181 | "pay": "N/A", 182 | "skills": [ 183 | "Data Pipeline" 184 | ], 185 | "street_address_1": "", 186 | "street_address_2": "", 187 | "onet15_code": "15-1031.00", 188 | "onet15_friendly_title": "Computer Software Engineers, Applications", 189 | "onet17_code": "15-1132.00", 190 | "onet17_friendly_title": "Software Developers, Applications", 191 | "carotene2p2_code": "15.1272", 192 | "carotene2p2_friendly_title": "Data Developer", 193 | "carotene3_code": "15.1272", 194 | "carotene3_friendly_title": "Data Developer", 195 | "normalized_title": "Data Developer", 196 | "date_posted": "2022-07-09T12:37:10-04:00", 197 | "job_level": "3", 198 | "apply_requirements": [ 199 | "IsExternal" 200 | ], 201 | "account_did": "A7909S6JFDSX73HW6K0", 202 | "city": "Irving", 203 | "description_teaser": "Big Data Developer Irving, TX Full Time Job Description Minimum experience of 6 years working as a Bigdata developer Ability to develop data integration and transformation code pipelines in object-oriented scripting language: PySpark Python in Spark Exper", 204 | "display_job_id": "LI13-10440_3153205202", 205 | "apply_url": "https://click.appcast.io/track/enrecy0?cs=lxb&exch=4s&jg=2wis&bid=lqoIfZS7Ja_LCveufxvy9g==&ob=Xxps_NXaD8VEVqiwSSFTWg==", 206 | "company_image_url": "", 207 | "applications": "0", 208 | "mastercommunitylist": [ 209 | "CMAL" 210 | ] 211 | } 212 | ] 213 | } 214 | } 215 | ``` 216 | 217 |   218 | 219 | ----------- 220 | 221 | # Job Recommendation service - Wants Endpoint 222 | # Contents 223 | 224 | - [Summary](#summary) 225 | - [Request structure](#request-structure) 226 | - [Response Structure](#response-structure-v1--default) 227 | - [Response Structure](#response-structure-v2) V2 version 228 | 229 | ---------------------------- 230 | # Summary 231 | 232 | Given a job title and, other params such as location filter and compensation filter then the Job Recommendation Service provides recommendations of relevant and similar jobs. 233 | This service will trigger a jobsearch v1 based on the given parameters. 234 | ---------------------------- 235 | # Request structure 236 | The service supports `GET` and `POST` requests to: 237 | https://api.careerbuilder.com/consumer/recommendations/wants. 238 | 239 | Version 2.0 is available 240 | This v2 will trigger a jobsearch v4 based on the given parameters and provide same response than platform endpoint. 241 | Request is the same model 242 | 243 | 244 | OAUTH credentials are **required** and Documentation for CareerBuilder authentication is provided [here](https://apimanagement.cbplatform.link/#/oauth/faq) by the Platform Software team. 245 | 246 | The request parameters: 247 | 248 | | Param | Type | Required | Description | 249 | |----------------------|--------------|-----------|---------------------------------------------| 250 | | `title` | String | **False** | This needs to be a valid job title. | 251 | | `compensationFilter` | Object | **False** | This needs to be a valid compensationFilter | 252 | | `hostSite` | String | **False** | Hostsite for source `title`. Value is "US" | 253 | | `locationFilters` | List[Object] | **False** | This needs to be a valid locationFilter. | 254 | 255 |   256 | ### Full Request Example 257 | 258 | ```json 259 | { 260 | "title":"Report Analyst", 261 | "hostSite":"US", 262 | "compensationFilter":{ 263 | "type":"ANNUALIZED_TOTAL_AMOUNT", 264 | "range":{ 265 | "min":{ 266 | "currencyCode":"USD", 267 | "units":0 268 | }, 269 | "max":{ 270 | "currencyCode":"USD", 271 | "units":9999999 272 | } 273 | } 274 | }, 275 | "locationFilters":[ 276 | { 277 | "latLng":{ 278 | "latitude":32.81402, 279 | "longitude":-96.94889 280 | }, 281 | "distanceInMiles":50 282 | } 283 | ] 284 | } 285 | ``` 286 | ---------------------- 287 | # Response Structure V1 / Default 288 | 289 | Example response body: 290 | ```JSON 291 | { 292 | "forensics": [], 293 | "timing": { 294 | "time_received": "2022-07-19T09:02:00.000Z", 295 | "time_elapsed_milliseconds": 476 296 | }, 297 | "data": [ 298 | { 299 | "title": "Associate Report Analyst - Telecommute", 300 | "distance": 9, 301 | "score": 1.0, 302 | "jobDID": "J3R7WC68GS0N5J30Q1K", 303 | "employmentTypes": [ 304 | "FULL_TIME" 305 | ], 306 | "description": "UnitedHealthcare is a company that's on the rise. We're expanding in multiple directions, across borders and, most of all, in the way we think. Her...", 307 | "applicationUrls": [ 308 | "https://api.careerbuilder.com/v1/application/applylink?JobDID=J3R7WC68GS0N5J30Q1K&TrackingID=HY8NXZ3D&HostSite=US" 309 | ], 310 | "startDate": "2022-06-25T04:17:15.000Z", 311 | "endDate": "2022-03-25T00:00:00.000Z", 312 | "compensationInfo": { 313 | "type": "BASE", 314 | "min": { 315 | "units": 0, 316 | "nanos": "" 317 | }, 318 | "max": { 319 | "units": 0, 320 | "nanos": "" 321 | }, 322 | "entries": [ 323 | { 324 | "type": "BASE", 325 | "unit": "", 326 | "range": { 327 | "min": { 328 | "units": 0 329 | }, 330 | "max": { 331 | "units": 0 332 | } 333 | } 334 | } 335 | ] 336 | }, 337 | "companyID": "C8E59J6ZM4TR74GZK7L", 338 | "companyTitle": "UnitedHealth Group", 339 | "jobLocations": [ 340 | { 341 | "locationType": "LOCALITY", 342 | "postalAddress": { 343 | "regionCode": "US", 344 | "postalCode": "", 345 | "administrativeArea": "TX", 346 | "locality": "Dallas", 347 | "addressLines": [ 348 | "TX - Dallas" 349 | ] 350 | }, 351 | "latLng": { 352 | "latitude": 32.77666, 353 | "longitude": -96.79699 354 | }, 355 | "radiusMeters": 12 356 | } 357 | ], 358 | "onet": "13-1111.00", 359 | "jobTypeCodes": [ 360 | "JN010" 361 | ], 362 | "upgradeList": [ 363 | "JCPR0" 364 | ], 365 | "applyRequirements": [ 366 | "IsExternal" 367 | ], 368 | "displayFields": { 369 | "display_city": "Dallas", 370 | "hide_compensation": true 371 | }, 372 | "logo": "https://secure.icbdr.com/MediaManagement/FF/MH17FF6DB5Q8R948GFF.jpg" 373 | } 374 | ] 375 | } 376 | ``` 377 | 378 | 379 | # Response Structure V2 380 | 381 | Example response body: 382 | ```JSON 383 | { 384 | "data": { 385 | "records": [ 386 | { 387 | "city": "Denton", 388 | "state": "TX", 389 | "date_posted": "2023-04-09T07:37:40.1730000Z", 390 | "company_name": "UNT System", 391 | "expire_date": "2023-06-03T11:03:38.0270000Z", 392 | "id": "J3M0WQ70VQQB2RGPRL2", 393 | "has_quick_apply": false, 394 | "title": "UNT WISE Senior Administrative Specialist", 395 | "score": 1.0, 396 | "location": "US-TX-Denton", 397 | "job_details_url": "https://wwwtest.api.careerbuilder.com/v1/joblink?DID=J3M0WQ70VQQB2RGPRL2&recid=TR46E608F79F604FEEB46562438604D051", 398 | "description": "<b>Position Details</b><br /><br />Position Information<br /><br />UNT System Overview <br /><br />Welcome to the University of North Texas System . UNT System includes the University of North Texas in Denton , the University of North Texas at Dallas and the University of North Texas Health Science Center in Fort Worth. We are the only university system based exclusively in the robust Dallas-Fort Worth region and we are committed to transforming lives and creating economic opportunity through education. We are growing with the DFW region, enrolling a record 47,000+ students across our system and awarding nearly 12,000 degrees each year.<br /><br />Posting Title <br />UNT WISE Senior Administrative Specialist<br /><br />Department <br />UNT-UNTWISE - Workplace Inclusion-135351<br /><br />Job Location <br />Denton<br /><br />Full Time/Part Time <br />Full-Time<br ...", 399 | "text_pay": "N/A", 400 | "partner_id": "PGMPTNR", 401 | "is_programmatic": true, 402 | "work_from_home": "false", 403 | "product_id": "JCPGM2", 404 | "apply_requirements": [ 405 | "IsExternal" 406 | ], 407 | "job_type": "JTFT", 408 | "master_community_list": [ 409 | "CMAL", 410 | "CMIN" 411 | ] 412 | } 413 | ], 414 | "rec_id": "TR46E608F79F604FEEB46562438604D051" 415 | } 416 | } 417 | ``` 418 | 419 | 420 |   421 | 422 | ----------- 423 | -------------------------------------------------------------------------------- /Geocoding.md: -------------------------------------------------------------------------------- 1 | # Geocoding API 2 | 3 |   4 | 5 | # Contents 6 | 7 | - [Description](#description) 8 | - [Geocoding Request](#geocoding-request) 9 | - [Place ID Lookup Request](#place-id-lookup-request) 10 | - [Place ID Lookup Request Structure](#place-id-lookup-request-structure) 11 | - [Response Structure](#response-structure) 12 | - [Remarks and Recommendations](#remarks-and-recommendations) 13 | - [Reporting data quality issues](#reporting-data-quality-issues) 14 | - [Versioning](#versioning) 15 | 16 | ---------------------------- 17 | # Description 18 | 19 | This service makes use of two different requests: Geocoding Requests and Google place ID lookup. The two request types represent two different methods of obtaining geographic information for a query (latitude/longitude, locality, administrative areas, country, etc.) and are explained in more detail below. This service relies on Google's Geocoding API as its data vendor; Google's service is documented [here](https://developers.google.com/maps/documentation/geocoding/intro). Requests will be handled the same way regardless of HTTP method; use whichever method you find most convenient. 20 | 21 | ---------------------------- 22 | # Geocoding Request 23 | A Geocoding request contains at least one of (query, address, locality, postal_code, admin_area, country) that must be provided in the query string. 24 | 25 | Please note that although there is no requirement that requests contain the address field or that the query field be a complete street address, the intended use case for Google Geocoding, as stated by Google itself, is to geocode street addresses. Requests for individual cities, postal codes, etc. are liable to encounter data quality issues that Google may decline to address due to their API being used for unsupported request types. The Google Geo services intended to be used for non-street addresses are [Place Autocomplete](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceAutocomplete.md) and [Place Details](https://github.com/careerbuilder/DataScienceAPIDocumentation/blob/master/PlaceDetails.md). 26 | 27 | ### Headers and Version 28 | 29 | Version must be specified in the ```Accept``` header. 30 | 31 | E.g.: ```Accept: application/json;version=1.1``` 32 | 33 | See the [Versioning](#versioning) section for more information on Geocoding versioning. 34 | 35 | ### Request Structure 36 | 37 | Example URL: https://api.careerbuilder.com/core/geography/geocoding?address=5550%20Peachtree%20Pkwy&locality=Norcross&admin_area=GA&postal_code=30092&country=US 38 | 39 | 40 | | Parameter | Description | 41 | |------------|-------------| 42 | | address | Optional. A string containing address information, e.g. "5550 Peachtree Pkwy."" Other forms of location data may be passed in this field (such as postal codes or country names), but we recommend using the type-specific parameters when the location type of the data is known. This parameter is handled in the same way as the **query** parameter and the two cannot be used simultaneously. | 43 | | query | Optional. A string containing location information in any format, e.g. "5550 Peachtree Pkwy, Norcross, GA 30092."" This parameter is handled in the same way as the **address** parameter and the two cannot be used simultaneously. **IMPORTANT NOTE:** We recommend using the type-specific parameters (**locality**, **admin_area**, **country**, etc) when the location type of the data is known, as that generally yields more accurate results. If you still need to resort to using this parameter, and especially if the request may not correspond to to a *fully specified street address*, you should be prepared to gracefully handle responses where certain fields (e.g. **locality**) are missing. See the notes on the **location_type** response field and the [Remarks and Recommendations](#remarks-and-recommendations). | 44 | | locality | Optional. The locality, such as the city or neighborhood, that corresponds to an address. | 45 | | admin_area | Optional. The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it is the second, third, or fourth order subdivision in a country, dependency, or region. | 46 | | country | Optional. A country name or two-letter ISO-3166 country code. Used to limit the geographic scope of results to a particular country. Multiple pipe-delimited values may be supplied to limit results to a set of specified countries, e.g. ?query=Rome&country=IT|US. | 47 | | postal_code | Optional. The post code, postal code, or ZIP Code of an address. | 48 | | culture | Optional. The preferred ISO 639-1 language code for the response. If this parameter is omitted, the response will be returned in English. Note that the level of localization will vary for each culture. For example, the name "United States" may not have a localized name for every culture code. The geocoding service currently only supports a subset of the ISO-639-1 standard. Click [here](Data/GeocodingServiceSupportedLanguages.md) to view a full list of supported culture codes. | 49 | | territories_as_states | Optional. When enabled, dependent territories may be requested as administrative areas of their parent nation, and will also be returned as such. This parameter is necessary to validate, for instance, **locality=San Juan&admin_area=PR&country=US**. This functionality will only recognize territories and parent countries by their [two-digit ISO-3166-1 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), so requests such as **admin_area=Puerto Rico&country=USA** would not be remapped according to this parameter. Default value is false. | 50 | 51 | ---------------------- 52 | 53 | # Place ID Lookup Request 54 | 55 | A Google place ID is a unique identifier used by Google to identify locations/places in the Google Places Database and on Google Maps. The service accepts a valid place ID as a means to retrieve geographic information from Google via reverse geocoding. Requesting a location using a Google place ID requires that the request contains a place ID and a culture param if a language specification is desired. Additional location parameters will result in an HTTP 400 response. 56 | 57 | # Place ID Lookup Request Structure 58 | 59 | Example URL: https://api.careerbuilder.com/core/geography/geocoding?culture=en&place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA 60 | 61 | | Parameter | Description | 62 | |------------|-------------| 63 | | place_id | Required. Id provided by google that uniquely identifies locations based on the Google Places Database and in Google Maps. 64 | | culture | Optional. The preferred ISO 639-1 language code for the response. If this parameter is omitted, the response will be returned in English. Note that the level of localization will vary for each culture. For example, the name "United States" may not have a localized name for every culture code. The geocoding service currently only supports a subset of the ISO-639-1 standard. Click [here](Data/GeocodingServiceSupportedLanguages.md) to view a full list of supported culture codes. | 65 | 66 |   67 | 68 | ---------------------- 69 | # Response Structure 70 | 71 | All responses with an HTTP status of 200 will consist of a JSON object with a top-level "data" node containing the following elements: 72 | 73 | | Field | Description | 74 | |----------|-------------| 75 | | results | A JSON array of one or more objects containing geography data. If the request returns no results, the array will be empty. | 76 | | expiration_date | A date string in YYYY-MM-DD format representing the last day that this data may be used. Per our contract with Google, any data cached by users of the geocoding service must be discarded by this date. 77 | 78 |   79 | 80 | Each element of the returned **results** array will be formatted as follows: 81 | 82 | | | | 83 | |---|---| 84 | | admin_areas | A JSON array of up to 5 admin_area objects. See below for details on the structure of these objects. **This property is always present, but may be empty** if no admin areas were found. | 85 | | latitude | A double value specifying the location's latitude (in degrees) within the range [-90, +90]. **This property is always present.** | 86 | | longitude | A double value specifying the location's longitude (in degrees) within the range [-180, +180]. **This property is always present.** | 87 | | country | The country or region name of an address. **This property may be absent** if the location was not associated with a country. Some locations for which this occurs are "Europe", "Pacific Ocean", and "Gaza Strip" (a contested territory). | 88 | | locality | The populated place for the address. This typically refers to a city, but may refer to a suburb or a neighborhood in certain countries. **This property may be absent**. | 89 | | postal_code | The post code, postal code, or ZIP code of an address. **This property may be absent**. | 90 | | country_code | The two-letter ISO country code. **This property may be absent**. See "Country" for examples of when this might occur. | 91 | | formatted_address| A string containing the human-readable address of this location. Often this address is equivalent to the "postal address," which sometimes differs from country to country. (Note that some countries, such as the United Kingdom, do not allow distribution of true postal addresses due to licensing restrictions.) **This property may be absent**. | 92 | | location_type | The classification of the geographic entity returned. Possible values (in descending order of specificity) are STREET_ADDRESS, SUBLOCALITY, POSTAL_CODE, LOCALITY, ADMIN_AREA_2, ADMIN_AREA_1, STREET, COUNTRY, and UNKNOWN. The returned location type will reflect the most specific field present, based on the previously described order. If none of these fields are present (such as for the examples for which the Country field is absent), then the returned location type will be Unknown. **This property is always present and non-empty.** | 93 | | postcode_localities | A string array denoting all the localities contained in a postal code. **This property is only present when the result is a postal code that contains multiple localities,** and will never be empty (nor will it ever contain only one element). | 94 | | street_address | The official street line of an address relative to the area, as specified by the `locality` or `postal_code` properties. **This property may be absent**. | 95 | | sublocality | The neighborhood, borough, township, etc. for the address. Sublocalities are typically more specific than cities and may be returned even if the locality field is empty. **This property may be absent**. | 96 | | landmark | The full name of the landmark (such as a military base or island) returned by the service. **This property may be absent**. | 97 | | place_id | Google's unique identifier string corresponding to the returned location. | 98 | | viewport | A bounding box describing a rectangle that encloses the location. The viewport field contains two coordinate objects -- **northeast** and **southwest** -- each with **lat** and **lng** decimal values. It also contains a **suggested_radius** decimal field that contains the distance in miles from the center of the viewport to a corner. **This property and its elements are always present and non-empty.** | 99 | | metropolitan_statistical_area | The metropolitan statistical area containing the location. An object containing two fields, the title of the area and an integer code for the area. Metropolitan statistical areas are specific to the US. **This property may be absent**. | 100 | | designated_market_areas | An object array of the designated market areas containing the location. Designated market areas may overlap and thus a location may be in more than one designated market area. Designated market areas are specific to the continental US. See below for details on the structure of these objects. **This property may be absent and the array may be empty**. | 101 | | partial_match | A Boolean value that, when true, indicates that the geocoder did not return an exact match for the original request, though it was able to match part of the requested address. You may wish to examine the original request for misspellings and/or an incomplete address.
Partial matches most often occur for street addresses that do not exist within the locality you pass in the request. Partial matches may also be returned when a request matches two or more locations in the same locality. For example, "21 Henr St, Bristol, UK" will return a partial match for both Henry Street and Henrietta Street. Note that if a request includes a misspelled address component, the geocoding service may suggest an alternative address. Suggestions triggered in this way will also be marked as a partial match. **This property is always present.** | 102 | 103 |   104 | 105 | Each element of the returned **admin_areas** array will be formatted as follows: 106 | 107 | | | | 108 | |---|---| 109 | | short_name | The abbreviated form of the administrative area's name. This will vary by country and administrative division level. In the US, states (admin_area level 1) will use the state abbreviation (e.g. "GA"), and counties will use the full county name (e.g. "Gwinnett County"). **This property is always present and non-empty.** | 110 | | long_name | The unabbreviated form of the administrative area's name. **This property is always present and non-empty.** | 111 | | level | An integer between 1 and 5 inclusive specifying the hierarchal level at which this administrative area resides. In the US, states will be returned with a level of 1 and counties with a level of 2. **This property is always present and non-empty.** | 112 | 113 |   114 | 115 | Each element of the returned **designated_market_areas** array will be formatted as follows: 116 | 117 | | | | 118 | |---|---| 119 | | name | The name of the DMA, e.g. "Atlanta, GA." **This property is always present and non-empty.** | 120 | | id | The integer ID of the DMA. E.g. for the Atlanta, GA DMA, the ID is 524. **This property is always present and non-empty.** | 121 | 122 |   123 | 124 | ----------- 125 | # Remarks and Recommendations 126 | 127 | One common use case of the geocoding API is in normalizing location queries for search purposes. Occasionally, such applications may have the design goal of performing a "contained-in" search for some entities, such as states and countries ("return all results in Texas"), and for other entities, performing a radius search ("return all results within N mi/km of this point). If this describes your use case, the following logic is recommended: 128 | 129 | | | | 130 | |---|---| 131 | | country | **Contained-in search.** | 132 | | admin_area_1 or admin_area_2 | **Contained-in search.** These entities typically represent larger regions such as states, provinces, or counties. | 133 | | admin_area_3 and below | **Radius search.** In the United States, third-level administrative areas represent US townships, which are more similar in size and function to towns or cities than to counties or states. In other countries, third-level administrative areas and below typically represent similar location types. | 134 | | locality or sublocality | **Radius search.** | 135 | | postal_code | **Radius search.** | 136 | | street or street_address | **Radius search.** | 137 | 138 | 139 |   140 | 141 | ----------- 142 | # Reporting Data Quality Issues 143 | 144 | There are multiple ways to formulate a request for a given geographic entity. For example, while 145 | the following requests bodies are all conceptually queries about Chicago, IL, they are all unique 146 | queries that are handled in different ways by Google and cached separately by DSAD: 147 | 148 | - `query=chicago, il` 149 | - `query=chicago il` 150 | - `query=chicago, illinois` 151 | - `query=chicago, il, us` 152 | - `query=chicago, il&country=usa` 153 | - `query=chicago, illlinois&country=united states` 154 | - `query=chicago&admin_area=illinois&country=us` 155 | - `locality=chicago&admin_area=il&country=usa` 156 | - `locality=chicago&query=chigago illinois&country=usa` 157 | - `locality=chicago illinois&query=il usa&country=united states` 158 | - `locality=chicago&query=illinois&country=united states` 159 | - etc. 160 | 161 | As you can see, there are tens if not hundreds of ways to formulate a query for chicago using the 162 | city, state, and country name alone, and that is not including spelling variants (e.g. NYC, NY, 163 | New York, etc.) and misspellings. As previously mentioned, all of these are handled differently by 164 | Google and potentially return different results. If you have a problem with the response for a 165 | request of, for example,`query=chicago, il`, then asking Google to change the response for 166 | `query=chicago illinois` will not necessarily result in a change for the former. 167 | 168 | When investigating data quality issues, **DSAD and Google need to know the exact character for 169 | character request you are sending to `/core/geography/geocoding`**. It is not sufficient to simply 170 | report 'When I run a query for Chicago I get an unexpected value for the `foo` field on the 171 | response'. Such a request contains no actionable information which DSAD or Google could use to 172 | investigate your issue and will at best delay resolution while we ask you to provide reproduction 173 | steps and at worst lead to a resolution for a completely different query than the one your code is 174 | actually sending (and therefore potentially not fixing your actual query at all). 175 | 176 | When submitting a data quality report to DSAD please ensure you include the following information: 177 | - Confirm you are calling `/core/geography/geocoding`. There are multiple Geography related services 178 | at CB and just because your code is working with geo information, that doesn't mean it came from 179 | `/core/geography/geocoding`. 180 | - Provide the region you are calling in. 181 | - Provide the actual character-for-character request that your code is sending. 182 | - Provide the response returned from the service for your request or at least the field or fields 183 | that you believe to be incorrect. 184 | 185 | For example: 186 | - I am calling `/core/geography/geocoding` 187 | - I am calling in the EU region 188 | - When I send the following request: `locality=chicago&query=chicago il, usa&country=us` 189 | - ... then `data.results.admin_areas[1].short_name` is `DuPage County` 190 | - ... I think it should instead be `Cook County` 191 | 192 | ----------- 193 | # Versioning 194 | The current API version is 1.1. The data returned from the service is unversioned. 195 | 196 | Geography is constantly changing as postal codes, cities, states, and countries are created and destroyed. Google, our vendor, doesn't publish an update policy and changes things as they see fit. 197 | 198 | Our general versioning strategy is available [here](/Versioning.md). 199 | --------------------------------------------------------------------------------