For Developers

Data included in the API

1. Occupational standards

The search occupations endpoint will allow you to query the currently published occupations.

The occupations by SOC endpoint will allow you to retrieve occupational standards which have been mapped to a standard occupational code. 

The occupations endpoint will allow you to retrieve an individual occupation for which you know the occupational code.

Occupations are also returned by other endpoints, wherever an occupation is returned additional occupational data can be expanded using the 'expand' parameter - see Requesting expanded information to be returned below for more information.

2. Get occupational routes

The routes endpoint will allow you to get an occupational route and all the occupations it contains.

3. Get green themes

The green theme endpoint will allow you to get occupations in the occupational route structure for a specific green theme.

4. Get occupational progression

The occupational progression endpoint will allow you to get occupations for which progression has been identified to or from a specific occupation.  The occupations could be in the same route or across routes.

5. Get technical education progression

The technical education progression endpoint will allow you to get information about progression from a specific T Level product, this could include other technical education, non-technical education and job titles.  If an associated apprenticeship is accelerated or not applicable for progression from the T Level it is indicated in the data.

6. Get custom map 

The custom map endpoint will allow you to get the occupation details in the occupational route structure for a specified list of occupations. These occupations could be in the same route or across routes.

7. Get lookup data

The lookup endpoints will provide you with, usually, static lookup data such as the names of states, types and levels.

Querying the API

The root URL of the API is located at:

https://occupational-maps-api.instituteforapprenticeships.org/

You will need to append it with the version you are querying and then concatenate the endpoint you wish to query, for example, to get information about the Early Years Educator occupation you would call

https://occupational-maps-api.instituteforapprenticeships.org/api/v1/Occupations/OCC0135

You will always need to pass your API key as a key-value pair in the header.  The key name is X-API-KEY

Requesting expanded information to be returned

A number of the endpoints accept an 'expand' parameter.  These are to enable you to expand the data returned in this endpoint without querying and joining onto an additional endpoint.

For example, if you wanted to get all the occupations on the digital route with their associated technical education products you could query

https://occupational-maps-api.instituteforapprenticeships.org/api/v1/digital?expand=occupation.products

This would return the route data and for every occupation also include the information about its technical education.

Multiple expansions can be requested as a comma-separated list.  For example, if you also wanted to retrieve typical job titles you would query

https://occupational-maps-api.instituteforapprenticeships.org/api/v1/digital?expand=occupation.typicaljobtitles,occupation.products

Whenever an occupation object is returned the occupation expansions are available.  These are as follows:

• occupation.overview - the occupation overview (typically one line) plain text
• occupation.summary - the occupational summary (HTML)
• occupation.soc - the Standard Occupational Classification the occupation is associated with
• occupation.maphierarchy - the Route, Pathway, Cluster Group, Cluster and Technical Level this occupation resides in
• occupation.typicaljobtitles - the typical job titles associated with each occupation whether each job title is considered a green job title or not.
• occupation.dutiesKSB - the duties, knowledge, skills and behaviours (KSBs) for the occupation and the relationships between duties and KSBs
• occupation.green - green information about the occupation including the classification and any themes and sub-themes the occupation belongs to.
• occupation.keywords - associated keywords 
• occupation.involvedemployers - the employers who were involved in creating the occupational standard
• occupation.links - web links and API endpoints for further information on the occupation.
• occupation.products - the technical education products associated with the occupation
  • products.links - web links for further information on the associated product. N.B. occupation.products must also be expanded.

It is possible to expand the hypermedia from the GreenTheme and Route responses by using green.links and route.links respectively.  For example,

https://occupational-maps-api.instituteforapprenticeships.org/api/v1/Routes?expand=route.links

Linked data (Hypermedia)

Where returned data is related to a webpage or another API endpoint, it is referenced in a Links array. This is usually returned only if requested as an expansion.

For example, if you query the routes endpoint and expand routes.links

https://occupational-maps-api.instituteforapprenticeships.org/api/v1/Routes?expand=routes.links

You will get the list of routes and also the URLs to link to the Institute's website or additional API endpoints.

Response

The response is returned as object serialised JSON.

Errors

If your request cannot be handled an HTTP response code other than 200 will be returned. 

• 400 Bad Request - generally indicates an issue with the request you have submitted.  It could be that you have exceeded the maximum URL length allowed (2048 chars).
• 403 Forbidden - generally indicates an issue with your API key or the way your API key is being provided.
• 404 Not Found - for a valid endpoint, this may mean that you have requested data which does not exist. For example, not every product has Technical Education Progression data.
• 429 Too Many Requests - you have exceeded the maximum number of requests within a period.

More details are available in the Interactive Endpoint Documentation.