Skip to content

Commit 3d68ace

Browse files
richardewell1862richardewell1862
committed
README and openapi file creation
1 parent e234415 commit 3d68ace

2 files changed

Lines changed: 286 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# SIC Code Lookup API
2+
3+
Fast, reliable access to official UK Standard Industrial Classification (SIC) Codes.
4+
5+
The SIC Code Lookup API returns simple, predictable JSON and is designed for lookup, validation, enrichment, and reporting use cases.
6+
7+
---
8+
9+
## OVERVIEW
10+
11+
The API provides two core capabilities:
12+
13+
1. Get SIC Description by Code
14+
Retrieve the official SIC Description for a given SIC Code.
15+
16+
2. Search SIC Codes by Description
17+
Retrieve SIC Codes whose Descriptions contain a given keyword.
18+
19+
---
20+
21+
## AUTHENTICATION
22+
23+
- To access this API you need a RapidAPI API key
24+
- Create a free RapidAPI.com account
25+
- Search for the SICCodeAPI service in API Hub and subscribe to the free plan
26+
- RapidAPI will provide an API key that can be used immediately
27+
- No additional authentication setup is required
28+
29+
---
30+
31+
## BASE URL
32+
33+
All requests are made through the RapidAPI gateway.
34+
35+
---
36+
37+
## ENDPOINTS
38+
39+
### 1. Get SIC Description by Code
40+
41+
Retrieve the official SIC Description for a given SIC Code.
42+
43+
Request:
44+
GET /SICCodeAPI/code
45+
46+
Query Parameters:
47+
- Name: code
48+
- Type: string
49+
- Required: Yes
50+
- Description: SIC code
51+
52+
Example:
53+
/SICCodeAPI/code?code=0111
54+
55+
Response (200):
56+
{
57+
"0111": "Grow cereals & other crops"
58+
}
59+
60+
---
61+
62+
### 2. Search SIC Codes by Description
63+
64+
Retrieve SIC Codes whose Descriptions contain a given keyword.
65+
66+
Request:
67+
GET /SICCodeAPI/description
68+
69+
Query Parameters:
70+
- Name: description
71+
- Type: string
72+
- Required: Yes
73+
- Description: Search keyword (case-insensitive)
74+
75+
Example:
76+
/SICCodeAPI/description?description=fishing
77+
78+
Response (200):
79+
{
80+
"0501": "Fishing",
81+
"03110": "Marine fishing",
82+
"03120": "Freshwater fishing"
83+
}
84+
85+
---
86+
87+
## RESPONSE FORMAT
88+
89+
All successful responses return a JSON object where:
90+
- Keys are SIC Codes (strings)
91+
- Values are official SIC Descriptions
92+
93+
Example
94+
{
95+
"<sic_code>": "<description>"
96+
}
97+
98+
---
99+
100+
## ERRORS
101+
102+
If no matching SIC Code or Description is found, the API may return an empty JSON object or an error response depending on the request.
103+
104+
---
105+
106+
## NOTES
107+
108+
- All endpoints are read-only
109+
- No request body is required
110+
- Results are deterministic and based on official SIC classifications
111+
- The /SICCodeAPI/description endpoint may return multiple results
112+
113+
---
114+
115+
## PRICING
116+
117+
- The API is currently available under a free plan with up to 10,000 requests per month
118+
- No subscription fees
119+
- No overage charges
120+
- Requests above the monthly quota are blocked
121+
- Higher-volume plans may be introduced if demand requires
122+
123+
For higher-volume usage and pricing enquiries:
124+
enquiries@spatialdays.com
125+
126+
---
127+
128+
## TYPICAL USE CASES
129+
130+
- Business classification and validation
131+
- Data enrichment for company records
132+
- Compliance and regulatory tooling
133+
- Analytics and reporting workflows

‎openapi.yaml‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
openapi: 3.0.3
2+
info:
3+
title: SIC Code Lookup API
4+
version: 1.0.0
5+
description: Retrieve the official description for a specific SIC Code or retrieve SIC Codes whose descriptions contain a given keyword.
6+
7+
servers:
8+
- url: https://siccodeapi.p.rapidapi.com
9+
10+
components:
11+
securitySchemes:
12+
RapidApiKey:
13+
type: apiKey
14+
in: header
15+
name: X-RapidAPI-Key
16+
RapidApiHost:
17+
type: apiKey
18+
in: header
19+
name: X-RapidAPI-Host
20+
21+
schemas:
22+
ErrorResponse:
23+
type: object
24+
required:
25+
- error
26+
properties:
27+
error:
28+
type: string
29+
30+
security:
31+
- RapidApiKey: []
32+
RapidApiHost: []
33+
34+
paths:
35+
/SICCodeAPI/code:
36+
get:
37+
summary: Get SIC Description by Code
38+
description: Retrieve the official SIC Description for a given SIC Code.
39+
parameters:
40+
- name: code
41+
in: query
42+
required: true
43+
schema:
44+
type: string
45+
description: SIC Code (e.g. 0111)
46+
responses:
47+
"200":
48+
description: JSON object mapping SIC Code to Description
49+
content:
50+
application/json:
51+
schema:
52+
type: object
53+
additionalProperties:
54+
type: string
55+
examples:
56+
example:
57+
value:
58+
"0111": "Grow cereals & other crops"
59+
"400":
60+
description: Missing or empty SIC Code parameter
61+
content:
62+
application/json:
63+
schema:
64+
$ref: "#/components/schemas/ErrorResponse"
65+
examples:
66+
missingCode:
67+
value:
68+
error: No code parameter provided.
69+
"403":
70+
description: Not authorized (missing RapidAPI headers or not subscribed)
71+
"404":
72+
description: SIC code not found
73+
content:
74+
application/json:
75+
schema:
76+
$ref: "#/components/schemas/ErrorResponse"
77+
examples:
78+
notFound:
79+
value:
80+
error: Code "0111" not found.
81+
"429":
82+
description: Rate limit exceeded
83+
"500":
84+
description: SIC Code data unavailable
85+
content:
86+
application/json:
87+
schema:
88+
$ref: "#/components/schemas/ErrorResponse"
89+
examples:
90+
dataUnavailable:
91+
value:
92+
error: SIC Code data is unavailable.
93+
94+
/SICCodeAPI/description:
95+
get:
96+
summary: Search SIC Codes by Description
97+
description: Retrieve SIC Codes whose Descriptions contain a given keyword.
98+
parameters:
99+
- name: descrip
100+
in: query
101+
required: true
102+
schema:
103+
type: string
104+
description: Search keyword (case-insensitive) e.g. "fishing"
105+
responses:
106+
"200":
107+
description: JSON object mapping SIC Codes to Descriptions
108+
content:
109+
application/json:
110+
schema:
111+
type: object
112+
additionalProperties:
113+
type: string
114+
examples:
115+
example:
116+
value:
117+
"0501": "Fishing"
118+
"03110": "Marine fishing"
119+
"03120": "Freshwater fishing"
120+
"400":
121+
description: Missing or empty description parameter
122+
content:
123+
application/json:
124+
schema:
125+
$ref: "#/components/schemas/ErrorResponse"
126+
examples:
127+
missingDescription:
128+
value:
129+
error: No description parameter provided.
130+
"403":
131+
description: Not authorized (missing RapidAPI headers or not subscribed)
132+
"404":
133+
description: No SIC Codes had Descriptions containing the keyword
134+
content:
135+
application/json:
136+
schema:
137+
$ref: "#/components/schemas/ErrorResponse"
138+
examples:
139+
notFound:
140+
value:
141+
error: Description "fishing" not found.
142+
"429":
143+
description: Rate limit exceeded
144+
"500":
145+
description: SIC Code data is unavailable
146+
content:
147+
application/json:
148+
schema:
149+
$ref: "#/components/schemas/ErrorResponse"
150+
examples:
151+
dataUnavailable:
152+
value:
153+
error: SIC Code data is unavailable

0 commit comments

Comments
 (0)