atlas-obscura-api 2.1.1 → 3.0.0

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.
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  # Atlas Obscura API (Scraper)
7
7
 
8
- > JavaScript NPM library for scraping **Atlas Obscura ([atlasobscura.com](atlasobscura.com))** [unofficial]
8
+ > JavaScript NPM library for scraping **Atlas Obscura ([atlasobscura.com](https://atlasobscura.com))** [unofficial]
9
9
  >
10
10
  > - Browser + Node.js (SSR)
11
11
  > - JavaScript / TypeScript
@@ -14,25 +14,29 @@
14
14
  > - AWS λ (lambda function)
15
15
  > - Chrome extension
16
16
  > - React native app
17
+ > - Docker container
17
18
  > - ...
18
19
 
19
- ## Install
20
+ ## 📦 Installation
21
+
22
+ Install the library using npm, yarn, or your preferred package manager:
20
23
 
21
24
  ```bash
22
25
  npm install atlas-obscura-api --save
23
- # yarn add atlas-obscura-api
24
26
  ```
25
27
 
26
- ## Usage and examples
28
+ ## 🚀 Usage and Examples
29
+
30
+ Explore how to use the library with practical code snippets and sample outputs below:
27
31
 
28
- - [All places](#All-places)
29
- - [Search](#Search)
30
- - [Show place by ID (short)](#Show-place-by-ID)
31
- - [Show place by ID (full)](#Show-place-by-ID)
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)
32
36
 
33
37
  ### All Places
34
38
 
35
- Give me all places locations
39
+ > Retrieve all places locations
36
40
 
37
41
  ```javascript
38
42
  import { atlasobscura } from 'atlas-obscura-api';
@@ -82,8 +86,8 @@ atlasobscura.search({ lat: 34.0522, lng: -118.2437 }).then((search) => console.l
82
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',
83
87
  url: '/places/cathedral-our-lady-angels',
84
88
  id: 1370,
85
- hide_from_maps: 'false',
86
- coordinates: [Object],
89
+ hide_from_maps: false,
90
+ coordinates: { lat: 34.05765, lng: -118.244944 },
87
91
  distance_from_query: '0.38'
88
92
  },
89
93
  {
@@ -94,8 +98,8 @@ atlasobscura.search({ lat: 34.0522, lng: -118.2437 }).then((search) => console.l
94
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',
95
99
  url: '/places/last-bookstore',
96
100
  id: 6159,
97
- hide_from_maps: 'false',
98
- coordinates: [Object],
101
+ hide_from_maps: false,
102
+ coordinates: { lat: 34.047738, lng: -118.249422 },
99
103
  distance_from_query: '0.45'
100
104
  },
101
105
  {
@@ -107,26 +111,24 @@ atlasobscura.search({ lat: 34.0522, lng: -118.2437 }).then((search) => console.l
107
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',
108
112
  url: '/places/wells-fargo-history-museum-los-angeles',
109
113
  id: 28174,
110
- hide_from_maps: 'false',
111
- coordinates: [Object],
114
+ hide_from_maps: false,
115
+ coordinates: { lat: 34.05283, lng: -118.25191 },
112
116
  distance_from_query: '0.47'
113
117
  }
114
118
  ];
115
119
  ```
116
120
 
117
- ### Show place by ID
121
+ ### Show Place by ID
118
122
 
119
- #### Short version (one quick request)
123
+ #### Short Version (One Quick Request)
120
124
 
121
125
  > Get place by id (short version)
122
126
 
123
- ````javascript
124
-
125
127
  ```javascript
126
128
  import { atlasobscura } from 'atlas-obscura-api';
127
129
 
128
130
  atlasobscura.placeShort(494).then((place) => console.log(place));
129
- ````
131
+ ```
130
132
 
131
133
  #### Results
132
134
 
@@ -139,7 +141,7 @@ atlasobscura.placeShort(494).then((place) => console.log(place));
139
141
  country: 'United States',
140
142
  location: 'Bridgeport, California',
141
143
  url: 'https://www.atlasobscura.com/places/bodie-state-historical-park',
142
- hide_from_maps: 'false',
144
+ hide_from_maps: false,
143
145
  physical_status: '',
144
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',
145
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',
@@ -149,9 +151,11 @@ atlasobscura.placeShort(494).then((place) => console.log(place));
149
151
  }
150
152
  ```
151
153
 
152
- #### Full version (two internal requests)
154
+ #### Full Detail (Two Internal Requests)
153
155
 
154
- > Get place by id (FULL version)
156
+ > Get place by ID (FULL version).
157
+ >
158
+ > Beware: it makes two requests internally
155
159
 
156
160
  ```javascript
157
161
  import { atlasobscura } from 'atlas-obscura-api';
@@ -161,57 +165,107 @@ atlasobscura.placeFull(494).then((place) => console.log(place));
161
165
 
162
166
  #### Results
163
167
 
164
- Same as short but with full description, tags, directions and more, ... (TBD)
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
+ ```
165
211
 
166
- ## Used by
212
+ ## Used By
167
213
 
168
214
  - Atlas Obscura Offline mobile app (Android, iOS)
169
215
  - 🤷
170
216
 
171
217
  ## Development
172
218
 
173
- ### Developing and debugging library
219
+ ### Developing and Debugging Library
220
+
221
+ Start the development server:
174
222
 
175
223
  ```bash
176
224
  yarn start
177
225
  ```
178
226
 
179
- ### Run demo locally
227
+ ### Run Demo Locally
180
228
 
181
- You can find and modify it in [`./demo.ts`](https://github.com/bartholomej/atlas-obscura-api/blob/master/demo.ts) file
229
+ You can find and modify it in [`./demo.ts`](https://github.com/bartholomej/atlas-obscura-api/blob/master/demo.ts) file:
182
230
 
183
231
  ```bash
184
232
  yarn demo
185
233
  ```
186
234
 
187
- ## Development (notes for me)
235
+ ## 📝 Development Notes
188
236
 
189
237
  ### Publish Stable
190
238
 
191
- ```shell
239
+ ```bash
192
240
  yarn release:patch
193
241
  # yarn release:minor
194
242
  # yarn release:major
195
243
  ```
196
244
 
197
- ### Publish next channel
245
+ ### Publish Next Channel
198
246
 
199
247
  1. Bump version `-beta.0` in `package.json`
200
- 2. `yarn release:beta`
248
+ 2. Run:
249
+
250
+ ```bash
251
+ yarn release:beta
252
+ ```
201
253
 
202
254
  ## Contribution
203
255
 
204
- I welcome you to customize this according to your needs ;)
256
+ Contributions are welcome! Feel free to customize this library according to your needs.
257
+
258
+ Pull requests for any improvements are greatly appreciated!
205
259
 
206
- Pull requests for any improvements would be great!
260
+ ## ⭐️ Show Your Support
207
261
 
208
- ## ⭐️ Show your support
262
+ If this project helped you, consider giving it a ⭐️!
209
263
 
210
264
  Give a ⭐️ if this project helped you!
211
265
 
212
266
  Or if you are brave enough consider [making a donation](https://github.com/sponsors/bartholomej) for some 🍺 or 🍵 ;)
213
267
 
214
- ## Privacy Policy
268
+ ## 🛡️ Privacy Policy
215
269
 
216
270
  I DO NOT STORE ANY DATA. PERIOD.
217
271
 
@@ -219,14 +273,14 @@ I physically can't. I have nowhere to store it. I don't even have a server datab
219
273
 
220
274
  That's why, with atlas obscura api, what happens on your device stays on your device till disappear.
221
275
 
222
- ## License
276
+ ## 📝 License
223
277
 
224
- Copyright &copy; 2022 [Lukas Bartak](http://bartweb.cz)
278
+ Copyright &copy; 2025 [Lukas Bartak](http://bartweb.cz)
225
279
 
226
280
  Proudly powered by nature 🗻, wind 💨, tea 🍵 and beer 🍺 ;)
227
281
 
228
- **This is unofficial, experimental, made for fun and it has nothing to do with Atlas Obscura ❤️ itself**
282
+ **This is unofficial, experimental, made for fun, and has nothing to do with Atlas Obscura ❤️ itself.**
229
283
 
230
284
  All contents are licensed under the [MIT license].
231
285
 
232
- [mit license]: LICENSE
286
+ [MIT license]: LICENSE
package/index.js CHANGED
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.atlasobscura = exports.AtlasObscura = void 0;
4
4
  const location_service_1 = require("./services/location.service");
5
5
  class AtlasObscura {
6
+ locationService;
6
7
  constructor(locationService) {
7
8
  this.locationService = locationService;
8
9
  }
@@ -18,7 +19,7 @@ class AtlasObscura {
18
19
  async placeFull(id) {
19
20
  const place = await this.locationService.placeByIdShort(id);
20
21
  const placeRich = await this.locationService.placeFull(place.url);
21
- return Object.assign(Object.assign({}, place), placeRich);
22
+ return { ...place, ...placeRich };
22
23
  }
23
24
  }
24
25
  exports.AtlasObscura = AtlasObscura;
@@ -7,7 +7,7 @@ export interface PlaceShort {
7
7
  country: string;
8
8
  location: string;
9
9
  url: string;
10
- hide_from_maps?: boolean;
10
+ hide_from_maps?: string;
11
11
  physical_status: string;
12
12
  thumbnail_url: string;
13
13
  thumbnail_url_3x2: string;
@@ -19,6 +19,8 @@ export interface PlaceExtend {
19
19
  description?: string[];
20
20
  tags?: Tag[];
21
21
  directions?: string[];
22
+ imageCover?: string;
23
+ images?: string[];
22
24
  }
23
25
  export interface Tag {
24
26
  title: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "atlas-obscura-api",
3
- "version": "2.1.1",
3
+ "version": "3.0.0",
4
4
  "description": "Atlas Obscura API in JavaScript. NPM library for scrapping atlasobscura.com",
5
5
  "main": "./index.js",
6
6
  "author": "BART! <bart@bartweb.cz>",
@@ -10,7 +10,7 @@
10
10
  "build": "tsc",
11
11
  "postbuild": "npm-prepare-dist -s postinstall -s prepare",
12
12
  "tsc": "tsc",
13
- "demo": "ts-node demo",
13
+ "demo": "tsx demo",
14
14
  "lint": "eslint ./src/**/**/* --fix",
15
15
  "test": "jest",
16
16
  "publish:next": "yarn && yarn build && yarn test --coverage true && npm publish --folder dist --tag beta",
@@ -22,8 +22,8 @@
22
22
  "release:major": "git checkout master && npm version major -m \"chore(update): major release %s 💥\""
23
23
  },
24
24
  "dependencies": {
25
- "cross-fetch": "^3.1.5",
26
- "node-html-parser": "^6.1.4"
25
+ "cross-fetch": "^4.0.0",
26
+ "node-html-parser": "^7.0.1"
27
27
  },
28
28
  "repository": {
29
29
  "url": "git+https://github.com/bartholomej/atlas-obscura-api.git",
@@ -46,7 +46,7 @@
46
46
  "api"
47
47
  ],
48
48
  "engines": {
49
- "node": ">= 14"
49
+ "node": ">= 20"
50
50
  },
51
51
  "license": "MIT",
52
52
  "module": "./index.js",
@@ -25,6 +25,9 @@ class PlacesScraper {
25
25
  let place = null;
26
26
  try {
27
27
  place = JSON.parse(data);
28
+ if (place && typeof place.hide_from_maps === 'string') {
29
+ place.hide_from_maps = place.hide_from_maps === 'true';
30
+ }
28
31
  }
29
32
  catch (error) {
30
33
  console.error('Error parsing placeById', id);
@@ -34,18 +37,29 @@ class PlacesScraper {
34
37
  async placeFull(url) {
35
38
  const data = await (0, fetchers_1.fetchPage)(url);
36
39
  const html = (0, node_html_parser_1.parse)(data);
37
- const descriptions = html.querySelectorAll('#place-body p').map((p) => p.innerHTML);
38
- const directions = html
39
- .querySelectorAll('.DDP__direction-copy p')
40
- .map((p) => p.innerHTML)
41
- .filter((x) => x !== '');
42
- const tags = html.querySelectorAll('.item-tags a.itemTags__link').map((x) => {
40
+ const descriptions = html.querySelectorAll('.place-body p').map((p) => p.innerHTML);
41
+ const sectionDirections = Array.from(html.querySelectorAll('section')).find((sec) => {
42
+ const h2 = sec.querySelector('h2');
43
+ return h2 && h2.textContent.trim() === 'Know Before You Go';
44
+ });
45
+ const directions = sectionDirections
46
+ ? Array.from(sectionDirections.querySelectorAll('p')).map((p) => p.textContent.trim())
47
+ : [];
48
+ const tags = html.querySelectorAll('.aon-pill-badge-component').map((x) => {
43
49
  return {
44
- title: x.innerHTML.trim(),
50
+ title: x.querySelector('.aon-pill-badge-text')?.innerHTML.trim(),
45
51
  link: x.attributes.href
46
52
  };
47
53
  });
48
- return { description: descriptions, directions: directions, tags: tags };
54
+ const slides = html.querySelectorAll('.swiper-slide');
55
+ const images = Array.from(slides)
56
+ .map((slide) => {
57
+ const img = slide.querySelector('img');
58
+ return img ? img.getAttribute('src') : null;
59
+ })
60
+ .filter(Boolean);
61
+ const imageCover = images[0];
62
+ return { description: descriptions, directions, tags, imageCover, images };
49
63
  }
50
64
  }
51
65
  exports.PlacesScraper = PlacesScraper;
package/utils.js CHANGED
@@ -2,9 +2,8 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.parseResults = void 0;
4
4
  const parseResults = (matches) => {
5
- var _a;
6
5
  let locations = null;
7
- if (matches && ((_a = matches[1]) === null || _a === void 0 ? void 0 : _a.length)) {
6
+ if (matches && matches[1]?.length) {
8
7
  try {
9
8
  locations = JSON.parse(matches[1]);
10
9
  }