carpark_hdb_sg.yaml
===
###### tags: `Microservice Docs` `yaml` `carpark_hdb_sg.yaml`
---

openapi: 3.0.1
info:
title: HDB Carpark Locations (SG)
x-subscribelink: carpark_hdb_sg
description: |+
This Data microservice retrieves the Singapore Housing Development Board's carpark information within Singapore HDB estates that includes location address, postal code and parking lot capacity for different types of vehicle by carpark location. Updated monthly.
The HDB POTH programme makes selected public and non-public datasets available to developers and companies to improve their service offerings to benefit the lives of Singapore citizens. Sentient.io is proud to partner with HDB to manage and facilitate the sharing of data for the POTH Programme.
Suggested Use Cases: Geo-targeting app with map feature, property development planning resource, or planning for vehicle-sharing app.
**Note:** As this microservice uses the GET method, developers using this microservice must remember to have their app encode all the input values to be URL friendly (i.e. all spaces and special characters must be replaced). Here’s a reference on [URL encoding](https://www.w3schools.com/tags/ref_urlencode.ASP).

x-additionalinfo : |+
**Refining queries in the filterdata field using filter types and match types**
The filterdata fields use elasticsearch’s syntax (specifically filter types and match types) to help further refine search results and provide greater flexibility in structuring more sophisticated queries.

**Filter Types:**
A filter type is a logic operator to which the search results must fulfill certain logical conditions to be returned. The supported match types are:

* **must** - All of the stated conditions must match. Equivalent to an AND operator.
> {"must":[{"match":{"mc":0}}]}
* **must_not** - All of the stated conditions must not match. Equivalent to a NOT operator.
> {"must_not":[{"match":{"postalcode":"570251"}}]}

* **should** - At least one of the stated conditions should match. Equivalent to an OR operator.
> {"should":[{"match_phrase":{"street":"ang mo kio"}}]}

* **filter** - All of the stated conditions that must match. However, results are not scored unlike the other filter types which returns results based on how well the conditions are met.
> {"filter":[{"match":{"street":"bishan"}}]}

For a more detailed guide on filter types, [refer to this](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/query-dsl-bool-query.html).

Filter types cannot be used alone and must be used in conjunction with a match type to complete the query.
**Match Types:**
A match type is a match operator nested within a filter type that fine-tunes the matching condition of the text search. The supported match types are:

* **match** - Search within a full text field for a single word
> {"match":{"street":"bishan"}}
* **match_phrase** - Search within a full text field
> {"match_phrase":{"street":"bishan street 24"}}
* **match_phrase_prefix** - Search within a full text field with prefix
> {"match_phrase_prefix":{"street":"bishan street 24"}}
* **term** - Returns results that contain an exact term in a provided field
> {"term":{"cpk_no":"ak19"}}
* **terms** - Returns results that contain one or more exact terms in a provided field
> {"terms":{"cpk_no":["ak19","be33"]}}
* **range** - Returns results that contain terms within a stipulated range
> {"range":{"car":{"gte":100}}}
> {"range":{"car":{"lte":500}}}
> {"range":{"car":{"gte":100,"lte":500}}}
* **exists** - Returns results that contain any indexed value for a field
> {"exists":{ "field": "postalcode"}}
For a more detailed guide to match types, [refer to this](https://www.elastic.co/guide/en/elasticsearch/reference/7.9/term-level-queries.html).

**Forming sophisticated queries using combinations of filter types (in JSON)**
Multiple filter types can be combined together in one query (written in JSON format) to form a very sophisticated query. Here’s one example below:

> {
> "must":[{"match":{"mc":0}}],
> "filter":[{"match":{"street":"bishan"}}],
> "should":[{"match_phrase":{"street":"ang mo kio"}}],
> "must_not":[{"match":{"postalcode":"570251"}}]
> }
**Sample Queries Based on Use Cases**
1. **Search for all carparks around 414 Bedok North Road**
Using a querystring only:

> querystring = "414 bedok north road"
2. **Search for all carparks within a 1KM radius from Tampines Mall**
Using a filterdata only:
> filterdata = {"filter":[{"geo_distance": {"distance": "1km","location": "1.3525,103.9447"}}]}

3. **Search for all carparks around Tampines with motorcycle parking**
Using both querystring + filterdata:

> querystring = tampines
> filterdata = {"filter":[ {"range":{"mc":{"gte":1}}} ]}

4. **Search for all lorry parking lots for Bishan Street 22**

Using both querystring + filterdata:

> querystring = "bishan street 22"
> filterdata = {"filter":[ {"range":{"lorry":{"gte":1}}} ]}
version: '0.1'
servers:
- url: 'https://api.sentient.io'
tags:
- name: "v0.1"
description: "Published Date - Oct 10, 2019"
paths:
/DaaS/prod/hdb/carpark:
get:
tags:
- v0.1
parameters:
- in: query
name: querystring
schema:
type: string
description: |+
Simple keyword search for matches in all searchable fields. Keywords separated by spaces will return results containing any of those keywords. For exact phrase match, put entire phrase in double quotes (" ").

If this field is set to null, by default the microservice will return all carparks (within the stated limit), which can be further refined through the filterdata field for more sophisticated queries.

example: BE33
default: false
- in: query
name: offset
schema:
type: integer
description: The offset of the record list ie the starting index
example: "0"
default: false
- in: query
name: limit
schema:
type: integer
description: The max records to return for the request. Default - 10, Max - 10000
example: "10"
default: false
- in: query
name: filterdata
schema:
type: string
description: |+
Refine the search further on any of the possible through the 4 filter types :
* must
* must_not
* should
* filter
default: false
example: |+
{"must":[{"match":{"mc":0}}],"filter":[{"match":{"street":"bishan"}}],"should":[{"match_phrase":{"street":"ang mo kio"}}],"must_not":[{"match":{"postalcode":"570251"}}]}
responses:
'200':
description: success response
content:
application/json:
schema:
$ref: '#/components/schemas/success'
example:
results:
total: 1
max_score: 7.510164
hits:
- _index: sentient_carpark_hdb_index
_type: dir_doc
_id: BE37
_score: 7.510164
_source:
cpk_no: BE37
block: BLK 282
street: BISHAN STREET 22
address: BLK 282 BISHAN STREET 22
source: hdb
xcoord: '29235.553'
ycoord: '37787.1371'
car: 402
lorry: 40
mc: 0
createddate: '2020-09-11'
lastupdated: '2020-09-11'
location:
lat: 1.3580079412271227
lon: 103.84442083770412
postalcode:
- '570278'
- '570279'
- '570280'
- '570281'
- '570282'
- '570283'
- '570284'
- '570285'
- '570286'
- '570287'
message: Successfully Processed
status: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorized'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/paymentrequired'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/notfound'
'419':
description: Input Field Missing
content:
application/json:
schema:
$ref: '#/components/schemas/inputfieldmissing'
'420':
description: Input Limit Exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/inputlimitexceeded'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/servererror'
'504':
description: Gateway Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/gatewaytimeout'
security:
- APIAuthorizer: []
components:
schemas:
success:
type: object
properties:
results:
type: object
example: {<Json Object>}
description: Json Object of returned results
properties:
total:
type: number
example: 986
description: Total number of records
max_score:
type: number
example: 17.995623
description: The highest score value
hits:
type: array
example: [{<JSON result Object}]
description: The list of Json result object
items:
type: object
properties:
_index:
type: string
description: Index group of the document
example: "sentient_carpark_hdb_index"
_type:
type: string
description: Content type of the document
example: "dir_doc"
_id:
type: string
description: Document ID
example: "K7scqWgBv3dNEHq2WvMo"
_score:
type: number
description: The document score for the search request
example: 17.995623
_source:
type: object
example: {<Json Object>}
description: Json Object of returned hits
properties:
cpk_no:
type: string
description: Carpark Number
example: AK19
block:
type: string
description: Address block no
example: "BLOCK 253"
street:
type: string
description: Address street or building name
example: "ANG MO KIO STREET 21"
address:
type: string
description: Address full address
example: "BLOCK 253 ANG MO KIO STREET 21"
source:
type: string
description: Dataset source
example: "hdb"
postalcode:
type: array
description: List of postal code
example: ["570253", "570254"]
items:
type: string
description: postal code
example: "570253"
xcoord:
type: string
description: SVY21 X coordinates (Note, SVY21 is a localised plane coordinate system used specifically by Singapore. For global GPS lat/long coordinates, refer to "location" object)
example: 28185.4359
ycoord:
type: string
description: SVY21 Y coordinates (Note, SVY21 is a localised plane coordinate system used specifically by Singapore. For global GPS lat/long coordinates, refer to "location" object)
example: 39012.6664
location:
type: object
description: WGS84 (World Geodetic System) lat/long coordinates. This is the standard coordinate system used Global Positioning System (GPS).
example: {"lat":1.364299477060462,"lon":103.8350609414261}
properties:
lat:
type: string
description: WGS84 (GPS) latitude
example: 1.37179535
lon:
type: string
description: WGS84 (GPS) longitude
example: 103.8469821
car:
type: number
description: Number of car parking lots
example: 18
lorry:
type: number
description: Number of lorry parking lots
example: 6
mc:
type: number
description: Number of motorcycle parking lots
example: 0
createddate:
type: string
description: Record first release date on sentient
example: "2019-10-17"
lastupdated:
type: string
description: Record last updated date on sentient
example: "2019-10-17"
message:
type: string
example: Successfully Processed
description: The detail description on the status
status:
type: string
example: Success
description: The status of the API call Success/Failure
unauthorized:
type: object
properties:
message:
type: string
example: Missing Authentication Token
status:
type: string
example: Failure
forbidden:
type: object
properties:
message:
type: string
example: Access Denied Unauthorized User
status:
type: string
example: Failure
paymentrequired:
type: object
properties:
message:
type: string
example: Insufficient Credits Kindly Top Up
status:
type: string
example: Failure
notfound:
type: object
properties:
message:
type: string
example: Invalid Request URL
status:
type: string
example: Failure
servererror:
type: object
properties:
message:
type: string
example: Internal Server Error
status:
type: string
example: Failure
gatewaytimeout:
type: object
properties:
message:
type: string
example: Request Timeout
status:
type: string
example: Failure
inputfieldmissing:
type: object
properties:
message:
type: string
example: Input Field Missing
status:
type: string
example: Failure
inputlimitexceeded:
type: object
properties:
message:
type: string
example: Input Limit Exceeded
status:
type: string
example: Failure
versions:
type: object
properties:
v0.1:
type: array
items:
oneOf:
- type: string
example: Published Date - Oct 10,2019
description: Initial version release
securitySchemes:
APIAuthorizer:
type: apiKey
name: x-api-key
in: header
x-amazon-apigateway-authtype: custom
description: Authentication is done using the x-api-key in the request header.