====== Address Lookup Service ======
The Hong Kong Government Address Lookup Service take a HTTP get request, and return the look up result in the default XML format, or JSON format. The addresses information for this API is supposed to be updated every month.

===== Basic Request and Result =====
The request URL is ''https://www.als.ogcio.gov.hk/lookup?q='', and the input could be any free text related to the address you are looking up, such as the street number, street name, building name, estate name, etc... The more correct information your provided in the query, the more accurate the results would be returned.

Assume you want to search the street number for ''100'', but since the query input is a free text, it might not understand the ''100'' is the street number or a part of the building name, and so it will give your any result related to your input.

<code> https://www.als.ogcio.gov.hk/lookup?q=THE_ADDRESS_IN_FREE_TEXT
</code>
==== Example 1: ====
Searching for the building ''The One'' [[https://www.als.ogcio.gov.hk/lookup?q=the%20one]]
<code> https://www.als.ogcio.gov.hk/lookup?q=the%20one
</code>
Result: (With the first one is what I am looking for)
<code>
<AddressLookupResult>
   <RequestAddress>
      <AddressLine>the_one</AddressLine>
   </RequestAddress>
   <SuggestedAddress>
      <Address>
         <PremisesAddress>
            <EngPremisesAddress>
               <BuildingName>THE ONE</BuildingName>
               <EngStreet>
                  <StreetName>NATHAN ROAD</StreetName>
                  <BuildingNoFrom>100</BuildingNoFrom>
               </EngStreet>
               <EngDistrict>
                  <DcDistrict>YTM</DcDistrict>
               </EngDistrict>
               <Region>KLN</Region>
            </EngPremisesAddress>
            <GeospatialInformation>
               <Northing>817874</Northing>
               <Easting>835811</Easting>
               <Latitude>22.2998</Latitude>
               <Longitude>114.1724</Longitude>
            </GeospatialInformation>
            <GeospatialInformation>
               <Northing>817879</Northing>
               <Easting>835833</Easting>
               <Latitude>22.2998</Latitude>
               <Longitude>114.1726</Longitude>
            </GeospatialInformation>
         </PremisesAddress>
      </Address>
      <ValidationInformation />
   </SuggestedAddress>
   .
   .
   .
</AddressLookupResult>
</code>

==== Example 2 ====
Searching for the ''100 Nathan'' [[https://www.als.ogcio.gov.hk/lookup?q=100%20nathan]]
<code>https://www.als.ogcio.gov.hk/lookup?q=100%20nathan</code>

Result: (With the first one is what I am looking for)
<code>
<AddressLookupResult>
   <RequestAddress>
      <AddressLine>100 nathan</AddressLine>
   </RequestAddress>
   <SuggestedAddress>
      <Address>
         <PremisesAddress>
            <EngPremisesAddress>
               <BuildingName>THE ONE</BuildingName>
               <EngStreet>
                  <StreetName>NATHAN ROAD</StreetName>
                  <BuildingNoFrom>100</BuildingNoFrom>
               </EngStreet>
               <EngDistrict>
                  <DcDistrict>YTM</DcDistrict>
               </EngDistrict>
               <Region>KLN</Region>
            </EngPremisesAddress>
            <GeospatialInformation>
               <Northing>817874</Northing>
               <Easting>835811</Easting>
               <Latitude>22.2998</Latitude>
               <Longitude>114.1724</Longitude>
            </GeospatialInformation>
            <GeospatialInformation>
               <Northing>817879</Northing>
               <Easting>835833</Easting>
               <Latitude>22.2998</Latitude>
               <Longitude>114.1726</Longitude>
            </GeospatialInformation>
         </PremisesAddress>
      </Address>
      <ValidationInformation />
   </SuggestedAddress>
   .
   .
   .
</AddressLookupResult>
</code>


===== Options =====
==== In HTTP Header ====
''Accept'' - Control the result in XML or JSON. The default option is ''application/xml'', but it could be changed to ''application/json'' for JSON result.

''Accept-Encoding'' - ''gzip'' if you want to the result to be zipped. The default option is no compression.

''Accept-Language'' - The query result language. Default is both Chinese and English, but it could change to either accept ''en'' for English, or ''zh-Hant'' for Traditional Chinese.

==== In Request Query ====
''n'' - Number of the address records to be returned. The following example force the number of returned result to be 1.
<code>https://www.als.ogcio.gov.hk/lookup?q=100%20nathan&n=1</code>



===== Additional Resource =====
The documentation of this API: [[https://www.als.ogcio.gov.hk/docs/Data_Dictionary_for_ALS_EN.pdf]]