> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkrmap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List hotspots
> Paginate and filter the NYC preview dataset.
Returns a paginated list of hotspots from the New York City preview dataset.
```bash theme={null}
curl -H "x-api-key: linkr_test_demo01" \
"https://linkrmap.com/api/v1/hotspots?network=WiFi%206&risk=Low&limit=5"
```
## Query parameters
| Parameter | Type | Default | Behavior |
| --------- | ------- | ------- | ------------------------------------------------------------------------ |
| `limit` | integer | `20` | Results per page. Clamped to **1..100**. |
| `offset` | integer | `0` | Results to skip. Minimum **0**. |
| `risk` | string | — | Case-insensitive **exact** match: `Low`, `Medium`, or `High`. |
| `network` | string | — | Case-insensitive **exact** match: `WiFi 5`, `WiFi 6`, or `WiFi 6E`. |
| `search` | string | — | Case-insensitive **substring** match across `name`, `owner`, and `note`. |
Only `risk` and `network` filter the list. `security` is returned on every record but is
**not** filterable, and `search` does **not** cover it.
`network` values contain a space. URL-encode it: use `?network=WiFi%206`, not
`?network=WiFi 6`.
## Response
```json theme={null}
{
"data": [
{
"id": 2,
"name": "Apt 3R - 247 E 10th St",
"lat": 40.7272,
"lng": -73.9832,
"mbps": 120,
"risk": "Low",
"owner": "@maria_r88",
"note": "Strong signal from the back room. Don't hog bandwidth pls.",
"signal": "Strong",
"network": "WiFi 6",
"security": "WPA3",
"uptime": "98.1%",
"rating": "4.6/5",
"avatar": "#4ECDC4",
"lastUsed": "5 minutes ago",
"locationImage": "https://images.unsplash.com/photo-1545324418-cc1a3fa10c00?w=800&q=80"
}
],
"meta": { "total": 29, "limit": 5, "offset": 0, "hasMore": true }
}
```
The `meta` object reports the filtered `total`, the `limit` and `offset` in effect, and
`hasMore` (whether `offset + limit` is below `total`).
## Hotspot schema
| Field | Type | Notes |
| --------------- | ------- | --------------------------------------------------------------------- |
| `id` | number | Unique id, 1–78 |
| `name` | string | Display name |
| `lat` | number | Latitude |
| `lng` | number | Longitude |
| `mbps` | number | Advertised speed |
| `risk` | string | `Low` · `Medium` · `High` |
| `owner` | string | Contributor handle, e.g. `@maria_r88` |
| `note` | string | Free-text note |
| `signal` | string | `Weak` · `Moderate` · `Good` · `Strong` · `Very Strong` · `Excellent` |
| `network` | string | `WiFi 5` · `WiFi 6` · `WiFi 6E` |
| `security` | string | `WPA2` · `WPA3` · `Open` · `WPA3-Enterprise` |
| `uptime` | string | **String**, e.g. `"96.8%"` — not a number |
| `rating` | string | **String**, e.g. `"4.3/5"` — not a number |
| `avatar` | string? | Optional accent color |
| `lastUsed` | string? | Optional relative timestamp |
| `locationImage` | string? | Optional image URL |
`uptime` and `rating` are **strings**, not numbers. Parse accordingly.
## OpenAPI
````yaml GET /api/v1/hotspots
openapi: 3.1.0
info:
title: Linkr Public API
version: 1.0.0
description: >-
Read-only API serving the Linkr New York City preview dataset (78 hotspots).
No write operations exist. The API key is a shape-checked demo key, not an
issued credential.
servers:
- url: https://linkrmap.com
description: Production
security:
- apiKey: []
paths:
/api/v1/hotspots:
get:
summary: List hotspots
description: Returns a paginated list of hotspots from the NYC preview dataset.
operationId: listHotspots
parameters:
- name: limit
in: query
description: Number of results per page. Clamped to 1..100.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
description: Number of results to skip. Minimum 0.
required: false
schema:
type: integer
minimum: 0
default: 0
- name: risk
in: query
description: Filter by risk level (case-insensitive exact match).
required: false
schema:
type: string
enum:
- Low
- Medium
- High
- name: network
in: query
description: >-
Filter by network type (case-insensitive exact match). Values
contain a space — URL-encode it, e.g. WiFi%206.
required: false
schema:
type: string
enum:
- WiFi 5
- WiFi 6
- WiFi 6E
- name: search
in: query
description: Case-insensitive substring match across name, owner, and note only.
required: false
schema:
type: string
responses:
'200':
description: A page of hotspots.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Hotspot'
meta:
$ref: '#/components/schemas/ListMeta'
'401':
description: Missing or malformed API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Hotspot:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Tony's Deli & Grocery
lat:
type: number
example: 40.7189
lng:
type: number
example: -73.9847
mbps:
type: number
example: 85
risk:
type: string
enum:
- Low
- Medium
- High
example: Low
owner:
type: string
example: '@tony_deli'
note:
type: string
example: Password on the counter next to the register.
signal:
type: string
example: Good
network:
type: string
example: WiFi 5
security:
type: string
example: WPA2
uptime:
type: string
description: String, not a number.
example: 96.8%
rating:
type: string
description: String, not a number.
example: 4.3/5
avatar:
type: string
example: '#FF6B6B'
lastUsed:
type: string
example: 12 minutes ago
locationImage:
type: string
example: https://images.unsplash.com/photo-1555396273-367ea4eb4db5?w=800&q=80
required:
- id
- name
- lat
- lng
- mbps
- risk
- owner
- note
- signal
- network
- security
- uptime
- rating
ListMeta:
type: object
properties:
total:
type: integer
example: 78
limit:
type: integer
example: 20
offset:
type: integer
example: 0
hasMore:
type: boolean
example: true
Error:
type: object
properties:
error:
type: string
example: Unauthorized
message:
type: string
example: >-
Invalid or missing API key. Include x-api-key header with a valid
key (linkr_test_* or linkr_live_*).
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
Value must match linkr_(test|live)_[a-zA-Z0-9]{6,}. This is a shape
check, not an issued credential.
````