atlas-obscura-api 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +323 -0
  3. package/package.json +1 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 BART!
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,323 @@
1
+ [![npm version](https://badge.fury.io/js/atlas-obscura-api.svg)](https://badge.fury.io/js/atlas-obscura-api)
2
+ [![Package License](https://img.shields.io/npm/l/atlas-obscura-api.svg)](https://www.npmjs.com/atlas-obscura-api)
3
+ [![Build & Publish](https://github.com/bartholomej/atlas-obscura-api/workflows/Publish/badge.svg)](https://github.com/bartholomej/atlas-obscura-api/actions)
4
+ [![codecov](https://codecov.io/gh/bartholomej/atlas-obscura-api/branch/master/graph/badge.svg?token=YQH9UoVrGP)](https://codecov.io/gh/bartholomej/atlas-obscura-api)
5
+
6
+ # Atlas Obscura API (Scraper)
7
+
8
+ > JavaScript NPM library for scraping **Atlas Obscura ([atlasobscura.com](https://atlasobscura.com))** [unofficial]
9
+ >
10
+ > - Browser + Node.js (SSR)
11
+ > - JavaScript / TypeScript
12
+ > - You can use in:
13
+ > - Firebase function
14
+ > - AWS λ (lambda function)
15
+ > - Chrome extension
16
+ > - React native app
17
+ > - Docker container
18
+ > - ...
19
+
20
+ ## 📦 Installation
21
+
22
+ Install the library using npm, yarn, or your preferred package manager:
23
+
24
+ ```bash
25
+ npm install atlas-obscura-api --save
26
+ ```
27
+
28
+ ## 🚀 Usage and Examples
29
+
30
+ Explore how to use the library with practical code snippets and sample outputs below:
31
+
32
+ - [All places](#all-places)
33
+ - [Search](#search)
34
+ - [Show place by ID (short)](#short-version-one-quick-request)
35
+ - [Show place by ID (full)](#full-detail-two-internal-requests)
36
+
37
+ ### All Places
38
+
39
+ > Retrieve all places locations
40
+
41
+ ```javascript
42
+ import { atlasObscura } from 'atlas-obscura-api';
43
+
44
+ atlasObscura.placesAll().then((places) => console.log(places));
45
+ ```
46
+
47
+ #### Results
48
+
49
+ ```javascript
50
+ [
51
+ { id: 46691, lat: 29.99022, lng: -95.336783 },
52
+ { id: 46850, lat: 36.709674, lng: -92.266472 },
53
+ { id: 46597, lat: 32.805765, lng: 35.169971 },
54
+ { id: 43701, lat: 54.415365, lng: -1.260063 },
55
+ { id: 46266, lat: 46.196648, lng: 8.848537 },
56
+ { id: 46282, lat: 46.236906, lng: -60.100201 },
57
+ { id: 46028, lat: 21.272772, lng: -157.823812 },
58
+ { id: 46736, lat: 39.635311, lng: -76.268685 },
59
+ { id: 45981, lat: 34.101644, lng: -118.329489 },
60
+ { id: 45455, lat: 42.929702, lng: -75.852011 },
61
+ { id: 46206, lat: 38.912474, lng: -77.037291 },
62
+ { id: 46081, lat: 32.930318, lng: -110.709229 }
63
+ ];
64
+ ```
65
+
66
+ ### Search
67
+
68
+ > Search places by coordinates
69
+
70
+ ```javascript
71
+ import { atlasObscura } from 'atlas-obscura-api';
72
+
73
+ atlasObscura.search({ lat: 34.0522, lng: -118.2437 }).then((search) => console.log(search));
74
+ ```
75
+
76
+ #### Results
77
+
78
+ ```javascript
79
+ [
80
+ {
81
+ title: 'Cathedral of Our Lady of the Angels',
82
+ subtitle:
83
+ "Crypt mausoleum in cathedral's basement contains relics of third century Roman martyr, Saint Vibiana.",
84
+ location: 'Los Angeles, California',
85
+ thumbnail_url:
86
+ 'https://img.atlasobscura.com/YmNZy_5DUKw21Ppt5B4Ik8zo4qjrc9RkkgT1tnAghcE/rs:fill:200:200:1/g:ce/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy8yMTky/MDAyOTQxXzEzNDEw/OTQxMDguanBn.jpg',
87
+ url: '/places/cathedral-our-lady-angels',
88
+ id: 1370,
89
+ hide_from_maps: false,
90
+ coordinates: { lat: 34.05765, lng: -118.244944 },
91
+ distance_from_query: '0.38'
92
+ },
93
+ {
94
+ title: 'The Last Bookstore',
95
+ subtitle: 'This iconic L.A. bookshop is housed in an abandoned bank—both symbolic and chic.',
96
+ location: 'Los Angeles, California',
97
+ thumbnail_url:
98
+ 'https://img.atlasobscura.com/6XpPQSE2YVsqTDOuvfx9ZHsYY0NfmX7oLzEUL87DL4A/rs:fill:200:200:1/g:ce/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy8xMmI0/MzBkMDJjZjc2MjBj/ODJfbGIxLmpwZw.jpg',
99
+ url: '/places/last-bookstore',
100
+ id: 6159,
101
+ hide_from_maps: false,
102
+ coordinates: { lat: 34.047738, lng: -118.249422 },
103
+ distance_from_query: '0.45'
104
+ },
105
+ {
106
+ title: 'Wells Fargo History Museum',
107
+ subtitle:
108
+ 'Hidden in one of the skyscrapers on Bunker Hill, this museum features an 1895 stagecoach and peers into California’s gold-lined history.',
109
+ location: 'Los Angeles, California',
110
+ thumbnail_url:
111
+ 'https://img.atlasobscura.com/27GLJ0vkGogC-l1AK5CuJKxS5FrBcNrcOROTWja4FAc/rs:fill:200:200:1/g:ce/c:2483:1655:nowe:2:126/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy80Mjg4/ZWJjZC0zYmNhLTQw/MTgtYTMzOC0wMTkz/M2FjNzVmZGIxMmQ4/MmVlYTgyY2IwMTM4/NTZfSU1HXzIwMTgw/ODI5XzE0NTE0NS5q/cGc.jpg',
112
+ url: '/places/wells-fargo-history-museum-los-angeles',
113
+ id: 28174,
114
+ hide_from_maps: false,
115
+ coordinates: { lat: 34.05283, lng: -118.25191 },
116
+ distance_from_query: '0.47'
117
+ }
118
+ ];
119
+ ```
120
+
121
+ ### Show Place by ID
122
+
123
+ #### Short Version (One Quick Request)
124
+
125
+ > Get place by id (short version)
126
+
127
+ ```javascript
128
+ import { atlasObscura } from 'atlas-obscura-api';
129
+
130
+ atlasObscura.placeShort(494).then((place) => console.log(place));
131
+ ```
132
+
133
+ #### Results
134
+
135
+ ```javascript
136
+ {
137
+ id: 494,
138
+ title: 'Bodie State Historic Park',
139
+ subtitle: 'Standing in a state of "arrested decay," this ghost town allows for a detailed peek into Gold Rush life in an unusually harsh climate.',
140
+ city: 'Bridgeport',
141
+ country: 'United States',
142
+ location: 'Bridgeport, California',
143
+ url: 'https://www.atlasobscura.com/places/bodie-state-historical-park',
144
+ hide_from_maps: false,
145
+ physical_status: '',
146
+ thumbnail_url: 'https://img.atlasobscura.com/DzPFF3feclAXS5apzZq6HqIgaKUSxGzIEKTfCpnfKxY/rs:fill:200:200:1/g:ce/c:815:543:nowe:0:633/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
147
+ thumbnail_url_3x2: 'https://img.atlasobscura.com/uCGcoetx8YfBtMOBo4oe1_6wUF7CM8AOK3L04aN9cg0/rs:fill:204:136:1/g:ce/c:815:543:nowe:0:633/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
148
+ coordinates: { lat: 38.208804, lng: -119.014163 },
149
+ nearby_places: [],
150
+ nearby_foods: []
151
+ }
152
+ ```
153
+
154
+ #### Full Detail (Two Internal Requests)
155
+
156
+ > Get place by ID (FULL version).
157
+ >
158
+ > Beware: it makes two requests internally
159
+
160
+ ```javascript
161
+ import { atlasObscura } from 'atlas-obscura-api';
162
+
163
+ atlasObscura.placeFull(494).then((place) => console.log(place));
164
+ ```
165
+
166
+ #### Results
167
+
168
+ ```javascript
169
+ {
170
+ id: 494,
171
+ title: 'Bodie State Historic Park',
172
+ subtitle: 'Standing in a state of "arrested decay," this ghost town allows for a detailed peek into Gold Rush life in an unusually harsh climate.',
173
+ city: 'Bridgeport',
174
+ country: 'United States',
175
+ location: 'Bridgeport, California',
176
+ url: 'https://www.atlasobscura.com/places/bodie-state-historical-park',
177
+ hide_from_maps: false,
178
+ physical_status: '',
179
+ thumbnail_url: 'https://img.atlasobscura.com/KaOCwrZAjNgS3LMOK28iuTxHDnMsl3Yjy0L_bYpfF1I/rs:fill:200:200:1/g:ce/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
180
+ thumbnail_url_3x2: 'https://img.atlasobscura.com/aH-Qf5bAn0PE1Y6gf0b1xHdteWwXY0G99dMtlMEdWVk/rs:fill:204:136:1/g:ce/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
181
+ coordinates: { lat: 38.208804, lng: -119.014163 },
182
+ description: [
183
+ 'It was once the most lawless town in <a class="destination-link place-destination-link" href="https://www.atlasobscura.com/things-to-do/california">California</a>, a place where the fire bell ringing out the ages of those being laid to rest seemed to never stop its toll.',
184
+ "Today, what's left of Bodie is an eerie shell of the rough-and-tumble Gold Rush town, a window into a time long lost. Located in a very uniquely difficult climate of a &nbsp;desolate, high altitude plateau in the mountains but not in the woods, Bodie was not for the weak of heart—or feeble of constitutions.",
185
+ 'Nestled in the Bodie Hills, east of the Sierra Nevada mountains just north of <a href="https://www.atlasobscura.com/places/mono-lake">Mono Lake</a>, Bodie grew quickly from a quiet town of 500 people to a rowdy mining city. Its population exploded during the second boom of the California gold rush and the beginning of the Nevada silver rush. By 1879, Bodie boasted a population of 10,000 and had 65 saloons, 50 mining companies, a thriving red-light district in the north end of town, and the worst reputation in the state.',
186
+ `Despite its nasty reputation, gold- and silver-seekers came from every corner of the country to this environment to "see the elephant," as heading West was called. Bodie's promise of gold and silver fortunes even attracted the likes of railroad tycoon Leland Stanford. With fortune hunters pouring in from all over the world, opium dens, brothels and gambling dens popped up for every flavor of wild west entertainment. They came for the gold and stayed for the party.`,
187
+ 'Perhaps predictably, the mines quickly reached full capacity, and soon the mining companies cut their losses and closed down. Just as fast as Bodie had boomed, it busted, and the population had plummeted below 100 by 1888. Devoted locals held on until the 1920s, when Standard Mining closed down, but despite popular belief, Bodie was never completely abandoned. A few stragglers held down the fort until Bodie was absorbed as a National Landmark in 1962.',
188
+ 'Today the windswept streets of Bodie are open to the public. It is the best-preserved ghost town in California, with about 200 structures remaining (about 5% of its original glory), along with rusted-out cars and machinery and boarded-up mines. Many of the building interiors still contain original artifacts and cannot be entered. The state is now restoring many of the buildings, as well as building more tourist-friendly walkways and restroom facilities.',
189
+ 'Generally closed during the winter, the most reasonable access to Bodie is dusty highway 270, from highway 395. Call ahead during the swing months between winter and summer to check accessibility. Sometimes, a gate 1.5 miles out keeps away vehicles and advises hikers that the road is not fit to drive on.'
190
+ ],
191
+ directions: [
192
+ 'The Bodie Foundation runs a number of events every year. These include Friends of Bodie Day, which includes many historical reenactments; ghost walks; and photo workshops. The Stamp Mill, the only remaining industrial structure, is accessible only by guided tours. These tours can book up quickly. See Bodie Foundation link below for all listings. The park is northeast of Yosemite, 13 miles east of Highway 395 on Bodie Road (Hwy 270), seven miles south of Bridgeport.',
193
+ 'Before you set out to visit Bodie, there are a few things you should consider. Because of its altitude Bodie is very cold. Temperatures drop below freezing point 300 days a year. Dress accordingly.',
194
+ 'There is no gas station and no food for sale. So fill up your tank and pack a lunch.',
195
+ 'If you love photography, bring all your gear with you.'
196
+ ],
197
+ tags: [
198
+ { title: 'Abandoned', link: '/categories/abandoned' },
199
+ { title: 'Mining', link: '/categories/mining' },
200
+ { title: 'Ghost Towns', link: '/categories/ghost-towns' },
201
+ { title: 'Gold Rush', link: '/categories/gold-rush' },
202
+ { title: 'Ruins', link: '/categories/ruins' }
203
+ ],
204
+ imageCover: 'https://img.atlasobscura.com/Z7fkZefihgyRxzYQkbuv_xrdta4jxvASv_qBAfW_nYU/rt:fit/h:400/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
205
+ images: [
206
+ 'https://img.atlasobscura.com/Z7fkZefihgyRxzYQkbuv_xrdta4jxvASv_qBAfW_nYU/rt:fit/h:400/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85MDY0/ZDNkODljYjdmNjI0/ZWViMzA0NjU0ZjM4/ZGI5MTYzODVkZTRh/LmpwZw.jpg',
207
+ 'https://img.atlasobscura.com/a9V41OvE1zN7VchlVSGWtBSAcxfBT6GKrh-2UNbjzRU/rt:fit/h:400/q:81/sm:1/scp:1/ar:1/aHR0cHM6Ly9hdGxh/cy1kZXYuczMuYW1h/em9uYXdzLmNvbS91/cGxvYWRzL3BsYWNl/X2ltYWdlcy85dHR4/cDZiajVkNThlN2Zk/ZWQzMDNiMTA0MzI1/X0lNR185NDIyLlBO/Rw.jpg'
208
+ ]
209
+ }
210
+ ```
211
+
212
+ ## 📦 Docker
213
+
214
+ You can use this library in Docker.
215
+
216
+ We have [prepared a Docker image](https://hub.docker.com/r/bartholomej/atlas-obscura-api) for you.
217
+
218
+ ### Prebuilt image
219
+
220
+ ```bash
221
+ docker pull bartholomej/atlas-obscura-api
222
+ ```
223
+
224
+ ### Build & run your own image
225
+
226
+ > Build image
227
+
228
+ ```bash
229
+ docker build -t atlas-obscura-api .
230
+ ```
231
+
232
+ > Run image on port 3000
233
+
234
+ ```bash
235
+ docker run -p 3000:3000 atlas-obscura-api
236
+ ```
237
+
238
+ > Open http://localhost:3000
239
+
240
+ ### API endpoints
241
+
242
+ > Some examples
243
+
244
+ - `/movie/535121`
245
+ - `/search/quentin+tarantino`
246
+ - `/creator/2120`
247
+ - `/user-ratings/912-bart`
248
+
249
+ ## Used By
250
+
251
+ - Atlas Obscura Offline mobile app (Android, iOS)
252
+ - 🤷
253
+
254
+ ## Development
255
+
256
+ ### Developing and Debugging Library
257
+
258
+ Start the development server:
259
+
260
+ ```bash
261
+ yarn start
262
+ ```
263
+
264
+ ### Run Demo Locally
265
+
266
+ You can find and modify it in [`./demo.ts`](https://github.com/bartholomej/atlas-obscura-api/blob/master/demo.ts) file:
267
+
268
+ ```bash
269
+ yarn demo
270
+ ```
271
+
272
+ ## 📝 Development Notes
273
+
274
+ ### Publish Stable
275
+
276
+ ```bash
277
+ yarn release:patch
278
+ # yarn release:minor
279
+ # yarn release:major
280
+ ```
281
+
282
+ ### Publish Next Channel
283
+
284
+ 1. Bump version `-beta.0` in `package.json`
285
+ 2. Run:
286
+
287
+ ```bash
288
+ yarn release:beta
289
+ ```
290
+
291
+ ## Contribution
292
+
293
+ Contributions are welcome! Feel free to customize this library according to your needs.
294
+
295
+ Pull requests for any improvements are greatly appreciated!
296
+
297
+ ## ⭐️ Show Your Support
298
+
299
+ If this project helped you, consider giving it a ⭐️!
300
+
301
+ Give a ⭐️ if this project helped you!
302
+
303
+ Or if you are brave enough consider [making a donation](https://github.com/sponsors/bartholomej) for some 🍺 or 🍵 ;)
304
+
305
+ ## 🛡️ Privacy Policy
306
+
307
+ I DO NOT STORE ANY DATA. PERIOD.
308
+
309
+ I physically can't. I have nowhere to store it. I don't even have a server database to store it. So even if Justin Bieber asked nicely to see your data, I wouldn't have anything to show him.
310
+
311
+ That's why, with atlas obscura api, what happens on your device stays on your device till disappear.
312
+
313
+ ## 📝 License
314
+
315
+ Copyright &copy; 2025 [Lukas Bartak](http://bartweb.cz)
316
+
317
+ Proudly powered by nature 🗻, wind 💨, tea 🍵 and beer 🍺 ;)
318
+
319
+ **This is unofficial, experimental, made for fun, and has nothing to do with Atlas Obscura ❤️ itself.**
320
+
321
+ All contents are licensed under the [MIT license].
322
+
323
+ [MIT license]: LICENSE
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "atlas-obscura-api",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "Atlas Obscura API in JavaScript. NPM library for scrapping atlasobscura.com",
5
5
  "author": "BART! <bart@bartweb.cz>",
6
6
  "dependencies": {