Skip to main

API Technical Specs

Learn how to configure and leverage our services to achieve your toughest recruiting needs.
SaaS     |

Geocode a Parsed Job Order

POST /v10/geocoder/joborder

Get or insert geocode coordinate values (latitude/longitude) for a parsed job order.

Notes

Request Body

JobDatarequiredobject
The parsed JobData from the Sovren Job Order Parser. See Parse a Job Order
Providerrequiredstring
The Provider you wish to use to geocode the postal address (current options are "Google" or "Bing"). If not specified, we will default to Google.
If passing a ProviderKey, this field is required.
ProviderKeyrequiredstring
The Provider Key for the specified Provider. If using Bing you must specify your own provider key.
PostalAddressoptionalobject
The postal address you wish to geocode. For best results, specify as many of the PostalAddress fields as possible. If provided, this address will be used to get the geocode coordinates instead of the address included in the ParsedDocument (if present), however, the address in the ParsedDocument will not be modified.
PostalAddress.CountryCodeoptionalstring
The ISO 3166-1 alpha-2 code indicating the country for the postal address.
PostalAddress.PostalCodeoptionalstring
The postal code (or zip code) for the postal address.
PostalAddress.Regionoptionalstring
The region (i.e. State for U.S. addresses) for the postal address.
PostalAddress.Municipalityoptionalstring
The municipality (i.e. City for U.S. addresses) for the postal address
PostalAddress.AddressLineoptionalstring
The address line (i.e. Street address for U.S. address) for the postal address

Sample Request

{ ... 
"JobData" :  "...","Provider" :  "","ProviderKey" :  "",{ ... 
"CountryCode" :  "","PostalCode" :  "","Region" :  "","Municipality" :  "","AddressLine" :  ""
}
}

Response Body

Infoobject
Information explaining the outcome of the transaction.
Info.Codestring
A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success– Successful transaction

MissingParameter- A required parameter wasn't provided

InvalidParameter- A parameter was incorrectly specified

AuthenticationError- An error occurred with the credentials provided

InsufficientData- The address provided doesn't have enough granularity to be geocoded effectively

CoordinatesNotFound- The geocoding provider couldn't find any coordinates matching the provided address
Info.Messagestring
This message further describes the code providing additional detail.
Info.TransactionIdstring
The (GUID) id for a specific API transaction. Use this when contacting support@sovren.com about issues.
Info.EngineVersionstring
The version of the parsing/matching engine running under-the-hood.
Info.ApiVersionstring
The version of the API.
Info.TotalElapsedMillisecondsinteger
How long the transaction took on Sovren's server, in milliseconds. If the transaction takes longer to complete on the client side, that extra duration is solely network latency.
Info.TransactionCostdecimal
How many credits the transaction costs.How many credits the transaction costs.
Info.CustomerDetailsobject
Information about the customer who made the API call.
Value.CustomerDetails.AccountIdstring
The AccountId for the account.
Value.CustomerDetails.Namestring
The customer name on the account.
Value.CustomerDetails.IPAddressstring
The client IP Address where the API call originated.
Value.CustomerDetails.Regionstring
The region for the account, also known as the 'Data Center'.
Value.CustomerDetails.CreditsRemainingdecimal
The number of credits remaining to be used by the account.
Value.CustomerDetails.CreditsUseddecimal
The number of credits used by the account.
Value.CustomerDetails.MaximumConcurrentRequestsinteger
The number of requests that can be made at one time. If using sub-accounts, this is the maximum number of concurent requests across all accounts, not just this single sub-account.
Value.CustomerDetails.ExpirationDatedate
The date that the current credits expire.
Valueobject
Contains response data for the transaction.
Value.JobDataoptionalobject
The main output from the Sovren Job Parser containing the geocoded coordinates.
Value.JobData.CurrentJobIsManagementbool
Whether or not the job is a management position. Used by Sovren for AI Matching.
Value.JobData.HighestManagementScoreinteger
The management score. Used by Sovren for AI Matching.
Value.JobData.ManagementLevelbool
The management level. Used by Sovren for AI Matching.
Value.JobData.ExecutiveTypebool
What kind of executive position the job is, if any. Used by Sovren for AI Matching.
Value.JobData.MinimumYearsinteger
The minimum years experience for the job, if listed. Used by Sovren for AI Matching.
Value.JobData.MaximumYearsinteger
The maximum years experience for the job, if listed. Used by Sovren for AI Matching.
Value.JobData.MinimumYearsManagementinteger
The minimum years of management experience, if listed. Used by Sovren for AI Matching.
Value.JobData.MaximumYearsManagementinteger
The maximum years of management experience, if listed. Used by Sovren for AI Matching.
Value.JobData.RequiredDegreestring
The required educational degree, if listed. Used by Sovren for AI Matching.
Value.JobData.JobTitlesobject
The job titles found in the job. Used by Sovren for AI Matching.
Value.JobData.JobTitles.MainJobTitlestring
The main/overall job title.
Value.JobData.JobTitles.JobTitlestring[]
All job titles found in the job description.
Value.JobData.EmployerNamesobject
The employer names found in the job.
Value.JobData.EmployerNames.MainEmployerNamestring
The main/overall employer name.
Value.JobData.EmployerNames.EmployerNamestring[]
All employer names found in a job description.
Value.JobData.Degreesobject[]
The educational degrees found listed in the job. Used by Sovren for AI Matching.
Value.JobData.Degrees[i].Namestring
The name of the educational degree.
Value.JobData.Degrees[i].Typestring
The type of the educational degree.
Value.JobData.SchoolNamesstring[]
Any school names listed in the job.
Value.JobData.CertificationsAndLicensesstring[]
Any certifications/licenses listed in the job. Used by Sovren for AI Matching.
Value.JobData.LanguageCodesstring[]
Any languages listed in the job. Used by Sovren for AI Matching.
Value.JobData.CurrentLocationobject
The location of the job, if listed. Used by Sovren for AI Matching.
Value.JobData.CurrentLocation.CountryCodestring
The 2-letter ISO 3166 country code.
Value.JobData.CurrentLocation.PostalCodestring
The Postal or Zip code.
Value.JobData.CurrentLocation.Regionsstring[]
The Regions/Districts/States.
Value.JobData.CurrentLocation.Municipalitystring
The City/Municipality/Town.
Value.JobData.CurrentLocation.StreetAddressLinesstring
Street address lines.
Value.JobData.CurrentLocation.GeoCoordinatesobject
If geocoding has been done, this is the lat/lon for the location.
Value.JobData.CurrentLocation.GeoCoordinates.Latitudedecimal
The latitude, in degrees.
Value.JobData.CurrentLocation.GeoCoordinates.Longitudedecimal
The longitude, in degrees.
Value.JobData.CurrentLocation.GeoCoordinates.Sourcestring
The geocoding source, such as Google or Bing.
Value.JobData.TermsOfIntereststring[]
Terms of interest listed in the job.
Value.JobData.Ownersstring[]
Any owners of the job posting, if listed.
Value.JobData.SkillsDataobject[]
The skills found in the job. Used by Sovren for AI Matching.
Value.JobData.SkillsData[i].Rootstring
The name of the skills list that these taxonomies belong to.
Value.JobData.SkillsData[i].Taxonomiesobject[]
The skills taxonomies found in a resume.
Value.JobData.SkillsData[i].Taxonomies[j].Idstring
The id of the skills taxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].Namestring
The human-readable name.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomiesobject[]
The subtaxonomy children of this taxonomy (more specific groupings of skills).
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].SubTaxonomyIdstring
The id of the subtaxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].SubTaxonomyNamestring
The human-readable name of the subtaxonomy.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].PercentOfOverallinteger
The percent (0-100) of skills found in the subtaxonomy compared to all subtaxonomies.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].PercentOfParentinteger
The percent (0-100) of skills found in the subtaxonomy compared to other subtaxonomies in the parent taxonomy
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skillsobject[]
The skills from the subtaxonomy that were found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Requiredbool
True if this skill was listed as 'required' on the job description.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Idstring
The Id of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Namestring
The name of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].FoundInstring
Where the skill was found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].ExistsInTextstring
Whether or not this skill was found verbatim in the text.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variationsobject[]
The variations (synonyms) of this skill that were found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Requiredbool
True if this skill was listed as 'required' on the job description.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Idstring
The Id of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].Namestring
The name of the skill.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].FoundInstring
Where the skill was found.
Value.JobData.SkillsData[i].Taxonomies[j].SubTaxonomies[k].Skills[m].Variations[n].ExistsInTextstring
Whether or not this skill was found verbatim in the text.
Value.JobData.SkillsData[i].Taxonomies[j].PercentOfOverallinteger
The percent (0-100) of skills found in the document that belong to this taxonomy.
Value.JobData.JobMetadataobject
Metadata about the parsed job
Value.JobData.JobMetadata.PlainTextstring
The plain text that was used for parsing.
Value.JobData.JobMetadata.DocumentLanguagestring
The two-letter ISO 639-1 code for the language the document was written in.
Value.JobData.JobMetadata.DocumentCulturestring
The xx-XX language/culture value for the parsed document.
Value.JobData.JobMetadata.ParserSettingsstring
The full parser settings that were used during parsing.
Value.JobData.JobMetadata.DocumentLastModifieddate
The last-revised/last-modified date that was provided for the document. This was used to calculate all of the important metrics about skills and jobs.
Value.JobData.UserDefinedTagsstring[]
A list of User-Defined Tags that are assigned to this resume. These are used to filter search/match queries in the AI Matching Engine.

NOTE: you may add/remove these prior to indexing. This is the only property you may modify prior to indexing.

Sample Response

{ ... 
{ ... 
"Code" :  "string","Message" :  "string","TransactionId" :  "string","EngineVersion" :  "string","ApiVersion" :  "string","TotalElapsedMilliseconds" :  0,"TransactionCost" :  0,{ ... 
"AccountId" :  "string","Name" :  "string","IPAddress" :  "string","Region" :  "string","CreditsRemaining" :  0,"CreditsUsed" :  0,"ExpirationDate" :  "2021-12-31","MaximumConcurrentRequests" :  0
}
},
{ ... 
{ ... 
"CurrentJobIsManagement" :  true,"HighestManagementScore" :  0,"ManagementLevel" :  "string","ExecutiveType" :  "string","MinimumYears" :  0,"MaximumYears" :  0,"MinimumYearsManagement" :  0,"MaximumYearsManagement" :  0,"RequiredDegree" :  "string",{ ... 
"MainJobTitle" :  "string",[ ... 
"string"
]
},
{ ... 
"MainEmployerName" :  "string",[ ... 
"string"
]
},
[ ... 
{
"Name" :  "string","Type" :  "string"
}
],
[ ... 
"string"
],
[ ... 
"string"
],
[ ... 
"string"
],
{ ... 
"CountryCode" :  "string","PostalCode" :  "string",[ ... 
"string"
],
"Municipality" :  "string",[ ... 
"string"
],
{ ... 
"Latitude" :  0,"Longitude" :  0,"Source" :  "string"
}
},
[ ... 
"string"
],
[ ... 
"string"
],
[ ... 
{
"Root" :  "string",[ ... 
{
[ ... 
{
[ ... 
{
"Required" :  true,[ ... 
{
"Required" :  true,"Id" :  "string","Name" :  "string","FoundIn" :  "string","ExistsInText" :  true
}
],
"Id" :  "string","Name" :  "string","FoundIn" :  "string","ExistsInText" :  true
}
],
"PercentOfOverall" :  0,"PercentOfParent" :  0,"SubTaxonomyId" :  "string","SubTaxonomyName" :  "string"
}
],
"Id" :  "string","Name" :  "string","PercentOfOverall" :  0
}
]
}
],
{ ... 
"PlainText" :  "string","DocumentLanguage" :  "string","DocumentCulture" :  "string","ParserSettings" :  "string","DocumentLastModified" :  "2020-11-02"
},
[ ... 
"string"
]
}
}
}