@@ -19,3 +19,143 @@ and using Googles Maps API to extend place codes to full codes are in the
1919examples/ directory.
2020
2121More examples are on [ jsfiddle] ( https://jsfiddle.net/user/openlocationcode/fiddles/ ) .
22+
23+ # Public Methods
24+
25+ The following are the four public methods and one object you should use. All the
26+ other methods in the code should be regarded as private and not called.
27+
28+ ## encode()
29+
30+ ``` javascript
31+ OpenLocationCode .encode (latitude, longitude, codeLength) → {string}
32+ ```
33+
34+ Encode a location into an Open Location Code.
35+
36+ ** Parameters:**
37+
38+ | Name | Type | Description |
39+ | ------| ------| -------------|
40+ | ` latitude ` | ` number ` | The latitude in signed decimal degrees. Values less than -90 will be clipped to -90, values over 90 will be clipped to 90. |
41+ | ` longitude ` | ` number ` | The longitude in signed decimal degrees. This will be normalised to the range -180 to 180. |
42+ | ` codeLength ` | ` number ` | The desired code length. If omitted, ` OpenLocationCode.CODE_PRECISION_NORMAL ` will be used. For precision ` OpenLocationCode.CODE_PRECISION_EXTRA ` is recommended. |
43+
44+ ** Returns:**
45+
46+ The code for the location.
47+
48+ ** Exceptions:**
49+
50+ If any of the passed values are not numbers, an exception will be thrown.
51+
52+ ## decode()
53+
54+ ``` javascript
55+ OpenLocationCode .decode (code) → {OpenLocationCode .CodeArea }
56+ ```
57+
58+ Decodes an Open Location Code into its location coordinates.
59+
60+ ** Parameters:**
61+
62+ | Name | Type | Description |
63+ | ------| ------| -------------|
64+ | ` code ` | ` string ` | The code to decode. |
65+
66+ ** Returns:**
67+
68+ The ` OpenLocationCode.CodeArea ` object.
69+
70+ ** Exceptions:**
71+
72+ If the passed code is not a valid full code, an exception will be thrown.
73+
74+ ## shorten()
75+
76+ ``` javascript
77+ OpenLocationCode .shorten (code, latitude, longitude) → {string}
78+ ```
79+
80+ Remove characters from the start of an OLC code.
81+
82+ This uses a reference location to determine how many initial characters
83+ can be removed from the OLC code. The number of characters that can be
84+ removed depends on the distance between the code center and the reference
85+ location.
86+
87+ ** Parameters:**
88+
89+ | Name | Type | Description |
90+ | ------| ------| -------------|
91+ | ` code ` | ` string ` | The code to shorten. |
92+ | ` latitude ` | ` number ` | The latitude of the reference location. |
93+ | ` longitude ` | ` number ` | The longitude of the reference location. |
94+
95+ ** Returns:**
96+
97+ The code, shortened as much as possible that it is still the closest matching
98+ code to the reference location.
99+
100+ ** Exceptions:**
101+
102+ If the code is not a valid full code, or the latitude or longitude are not
103+ numbers, an exception will be thrown.
104+
105+ ## recoverNearest()
106+
107+ ``` javascript
108+ OpenLocationCode .recoverNearest (shortCode, referenceLatitude, referenceLongitude) → {string}
109+ ```
110+
111+ Recover the nearest matching code to a specified location.
112+
113+ This is the counterpart to ` OpenLocationCode.shorten() ` . This recovers the
114+ nearest matching full code to the reference location.
115+
116+ ** Parameters:**
117+
118+ | Name | Type | Description |
119+ | ------| ------| -------------|
120+ | ` shortCode ` | ` string ` | The code to recover. |
121+ | ` referenceLatitude ` | ` number ` | The latitude of the reference location. |
122+ | ` referenceLongitude ` | ` number ` | The longitude of the reference location. |
123+
124+ ** Returns:**
125+
126+ The nearest matching full code to the reference location.
127+
128+ ** Exceptions:**
129+
130+ If the short code is not valid, or the reference position values are not
131+ numbers, an exception will be thrown.
132+
133+ ## CodeArea
134+
135+ ``` javascript
136+ OpenLocationCode .CodeArea (latitudeLo, longitudeLo, latitudeHi, longitudeHi, codeLength) → {OpenLocationCode .CodeAre }
137+ ```
138+
139+ The ` OpenLocationCode.CodeArea ` class is used to return the area represented by
140+ a code. Because codes are areas, not points, this gives the coordinates of the
141+ south-west and north-east corners, the center, and the length of the code.
142+
143+ You can convert from a code to an area and back again like this:
144+
145+ ``` javascript
146+ var a = ' 796RWF8Q+WF'
147+ var area = OpenLocationCode .decode (a);
148+ var original_code = OpenLocationCode .encode (area .latitudeCenter , area .longitudeCenter , area .codeLength );
149+ ```
150+
151+ ** Attributes:**
152+
153+ | Name | Type | Description |
154+ | ------| ------| -------------|
155+ | ` latitudeLo ` | ` number ` | The latitude of the south-west corner. |
156+ | ` longitudeLo ` | ` number ` | The longitude of the south-west corner. |
157+ | ` latitudeHi ` | ` number ` | The latitude of the north-east corner. |
158+ | ` longitudeHi ` | ` number ` | The longitude of the north-east corner. |
159+ | ` latitudeCenter ` | ` number ` | The latitude of the center. |
160+ | ` longitudeCenter ` | ` number ` | The longitude of the center. |
161+ | ` codeLength ` | ` number ` | The length of the code that generated this area. |
0 commit comments