API
Documentation

The Skateparks.world REST API provides programmatic access to skatepark data. All endpoints require authentication.

Authentication Required

All API endpoints are protected. You must include a valid API key with every request. Contact api@skateparks.world to request access.

Authentication

Include your API key in every request using one of these methods:

Header (recommended)

X-API-Key: your_api_key_here

Bearer Token

Authorization: Bearer your_api_key_here

Example request

curl -X GET "https://skateparks.world/api/v1/parks" \
  -H "X-API-Key: your_api_key_here"

Base URL

All API endpoints are relative to:

https://skateparks.world/api/v1

Error Handling

The API uses standard HTTP status codes. Errors return a JSON object with an error field.

Status	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — invalid or missing API key
`404`	Resource not found
`500`	Internal server error

Error response example

{
  "error": "Unauthorized"
}

Park Object

A park has the following fields. All fields except the three marked required are optional when creating or updating.

Identity

Parameter	Type	Required	Description
`name`	string	Required	Name of the skatepark.
`country`	string	Required	Country name (e.g. "Denmark").
`city`	string	Required	City name (e.g. "Copenhagen").
`slug`	string	Optional	URL slug. Auto-generated from name + city if omitted.
`alias`	string	Optional	Alternative/local name for the park.

Location

Parameter	Type	Required	Description
`streetAddress`	string	Optional	Street address.
`zipcode`	string	Optional	Postal/zip code.
`lat`	number	Optional	Latitude coordinate.
`lng`	number	Optional	Longitude coordinate.

Classification

Parameter	Type	Required	Description
`type`	string	Optional	"indoor", "outdoor", "both", or "unknown" (default).
`status`	string	Optional	"open", "closed", "under_construction", or "unknown" (default).
`ownership`	string	Optional	Who owns the park (e.g. "Municipal", "Private").
`management`	string	Optional	Who manages/operates the park.
`builtBy`	string	Optional	Construction company or builder.
`designedBy`	string	Optional	Park designer.

Features (arrays of strings)

Parameter	Type	Required	Description
`obstacles`	string[]	Optional	e.g. ["halfpipe", "quarterpipe", "rail", "ledge", "bowl", "funbox"].
`facilities`	string[]	Optional	e.g. ["lights", "toilets", "parking", "water", "shop", "rental"].
`sports`	string[]	Optional	e.g. ["skateboarding", "bmx", "scooter", "inline"].
`surface`	string[]	Optional	e.g. ["concrete", "wood", "asphalt", "metal"].
`requirements`	string[]	Optional	e.g. ["helmet", "pads", "membership"].

Size & Year

Parameter	Type	Required	Description
`sizeSqm`	number	Optional	Park area in square meters.
`yearBuilt`	number	Optional	Year the park was built.

Contact & Socials

Parameter	Type	Required	Description
`website`	string	Optional	Park website URL.
`phone`	string	Optional	Phone number.
`email`	string	Optional	Contact email address.
`facebook`	string	Optional	Facebook page URL.
`instagram`	string	Optional	Instagram handle or URL.
`youtube`	string	Optional	YouTube channel URL.

Pricing

Parameter	Type	Required	Description
`priceAmount`	number	Optional	Entry price (e.g. 10.00). Use 0 for free admission; null means unknown.
`priceCurrency`	string	Optional	ISO 4217 currency code (e.g. "USD", "EUR", "DKK").
`paymentMethods`	string[]	Optional	e.g. ["cash", "card", "mobilepay"].
`membershipAvailable`	boolean	Optional	Whether membership/season pass is available.

Operations

Parameter	Type	Required	Description
`supervised`	boolean	Optional	Whether staff supervision is available.
`surveilled`	boolean	Optional	Whether the park has camera surveillance.
`hours`	object	Optional	Opening hours. See format below.

// hours format — each day is { open, close } or null (closed)
{
  "mon": { "open": "08:00", "close": "22:00" },
  "tue": { "open": "08:00", "close": "22:00" },
  "wed": { "open": "08:00", "close": "22:00" },
  "thu": { "open": "08:00", "close": "22:00" },
  "fri": { "open": "08:00", "close": "23:00" },
  "sat": { "open": "10:00", "close": "23:00" },
  "sun": null  // closed on Sunday
}

Content

Parameter	Type	Required	Description
`shortDescription`	string	Optional	Brief summary of the park.
`description`	string	Optional	Full description. Supports newlines.

Read-only fields (returned in responses)

Parameter	Type	Required	Description
`id`	uuid	Optional	Unique park ID. Auto-generated.
`countrySlug`	string	Optional	Auto-generated from country.
`citySlug`	string	Optional	Auto-generated from city.
`averageRating`	number	Optional	Computed average rating (1-5).
`ratingCount`	number	Optional	Total number of ratings.
`viewCount`	number	Optional	Page view count.
`featured`	boolean	Optional	Whether the park is featured.
`verified`	boolean	Optional	Whether location has been verified.
`createdAt`	timestamp	Optional	ISO 8601 creation date.
`updatedAt`	timestamp	Optional	ISO 8601 last update date.
`images`	array	Optional	Related images (included in GET by ID).
`videos`	array	Optional	Related videos (included in GET by ID).

Park Endpoints

GET/api/v1/parks

List all parks with pagination, or search by query.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Optional	Search query. If provided, returns matching parks instead of all.
`page`	number	Optional	Page number (default: 1).
`limit`	number	Optional	Results per page. Min 1, max 100 (default: 50).

Response

{
  "parks": [ { "id": "...", "name": "...", ... } ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1234,
    "totalPages": 25
  }
}

POST/api/v1/parks

Create a new skatepark. Only name, country, and city are required. All other park fields (see Park Object above) can be included.

Required fields

Parameter	Type	Required	Description
`name`	string	Required	Name of the skatepark.
`country`	string	Required	Country name.
`city`	string	Required	City name.

Plus any optional fields from the Park Object reference above (obstacles, facilities, phone, email, hours, pricing, etc.).

Example request

{
  "name": "Faelledparken Skatepark",
  "country": "Denmark",
  "city": "Copenhagen",
  "lat": 55.6945,
  "lng": 12.5728,
  "type": "outdoor",
  "status": "open",
  "obstacles": ["bowl", "quarterpipe", "rail", "ledge"],
  "facilities": ["lights", "parking"],
  "sports": ["skateboarding", "scooter"],
  "surface": ["concrete"],
  "phone": "+45 12345678",
  "email": "info@example.com",
  "instagram": "@faelledskatepark",
  "description": "A popular outdoor skatepark in the heart of Copenhagen."
}

Response (201)

{
  "park": { "id": "...", "name": "Faelledparken Skatepark", "slug": "faelledparken-skatepark-copenhagen", ... }
}

GET/api/v1/parks/:id

Get a single park by ID with all details, images, and videos.

Response

{
  "park": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Faelledparken Skatepark",
    "slug": "faelledparken-skatepark-copenhagen",
    "country": "Denmark",
    "city": "Copenhagen",
    "streetAddress": "Øster Allé 1",
    "zipcode": "2100",
    "lat": 55.6945,
    "lng": 12.5728,
    "type": "outdoor",
    "status": "open",
    "obstacles": ["bowl", "quarterpipe", "rail", "ledge"],
    "facilities": ["lights", "parking"],
    "sports": ["skateboarding", "scooter"],
    "surface": ["concrete"],
    "phone": "+45 12345678",
    "email": "info@example.com",
    "website": "https://example.com",
    "instagram": "@faelledskatepark",
    "facebook": "",
    "youtube": "",
    "priceAmount": null,
    "priceCurrency": "",
    "paymentMethods": [],
    "membershipAvailable": null,
    "supervised": false,
    "surveilled": false,
    "hours": null,
    "sizeSqm": 1200,
    "yearBuilt": 2018,
    "shortDescription": "Popular concrete park in central Copenhagen.",
    "description": "A popular outdoor skatepark in the heart of Copenhagen...",
    "averageRating": "4.20",
    "ratingCount": 15,
    "verified": true,
    "images": [
      { "id": "...", "url": "https://...", "caption": "...", "credit": "...", "order": 0 }
    ],
    "videos": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2025-11-20T14:22:00.000Z"
  }
}

PUT/api/v1/parks/:id

Update an existing park. Send only the fields you want to change. Accepts any field from the Park Object.

Example: update contact & features

{
  "phone": "+45 87654321",
  "email": "new@example.com",
  "instagram": "@newhandle",
  "obstacles": ["bowl", "halfpipe", "rail", "ledge", "funbox"],
  "hours": {
    "mon": { "open": "10:00", "close": "20:00" },
    "tue": { "open": "10:00", "close": "20:00" },
    "wed": { "open": "10:00", "close": "20:00" },
    "thu": { "open": "10:00", "close": "20:00" },
    "fri": { "open": "10:00", "close": "22:00" },
    "sat": { "open": "10:00", "close": "22:00" },
    "sun": null
  },
  "priceAmount": 5.00,
  "priceCurrency": "EUR"
}

Response

{
  "park": { "id": "...", "name": "...", ... }
}

DELETE/api/v1/parks/:id

Permanently delete a park and all related images, videos, and ratings.

Response

{ "success": true }

Search

GET/api/v1/search

Search parks by name, city, or country.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Required	Search query (must be non-empty).
`limit`	number	Optional	Max results. Min 1, max 50 (default: 20).

Response

{
  "parks": [ { "id": "...", "name": "...", ... } ],
  "query": "copenhagen",
  "count": 5
}

Coordinates

GET/api/v1/parks/coordinates

Get coordinates for all parks. Useful for rendering map markers. Cached for 1 hour.

Response

{
  "parks": [
    { "id": "...", "name": "...", "lat": 55.67, "lng": 12.56,
      "type": "outdoor", "status": "open", "flags": 13, ... },
    ...
  ]
}

flags packs the map filters into one number: 1 free, 2 lights, 4 skateboard, 8 BMX, 16 scooter, 32 inline (13 = free, skateboard and BMX).

Ratings

POST/api/v1/parks/:id/ratings

Submit a rating for a park. Rate-limited by IP address.

Request Body

Parameter	Type	Required	Description
`rating`	number	Required	Rating value, 1 to 5.
`displayName`	string	Required	Name to display with the review.
`comment`	string	Optional	Optional review text.
`email`	string	Optional	Optional email (not displayed publicly).
`createdAt`	string	Optional	ISO 8601 timestamp. Defaults to now. Use this to backdate ratings found online (e.g. "2023-06-15T12:00:00Z").

Response (201)

{
  "rating": {
    "id": "...",
    "parkId": "...",
    "rating": 4,
    "displayName": "Alex",
    "comment": "Great park!",
    ...
  }
}

Images

POST/api/v1/parks/:id/images

Upload a photo for a park. Uses multipart/form-data. Needs your API key (or a signed-in website account). New uploads start with pending status (moderation required); photo metadata such as GPS is removed.

Request Body (multipart/form-data)

Parameter	Type	Required	Description
`image`	File	Required	JPEG, PNG or WebP image (checked from the file itself), max 10 MB.
`email`	string	Optional	Contact email for moderation (a signed-in account's own email is used instead).
`caption`	string	Optional	Optional image caption/alt text.
`credit`	string	Optional	Photographer credit / copyright attribution.

Example (curl)

curl -X POST "https://skateparks.world/api/v1/parks/:id/images" \
  -H "X-API-Key: your_api_key_here" \
  -F "image=@photo.jpg" \
  -F "email=user@example.com" \
  -F "caption=Front view of the park" \
  -F "credit=John Doe"

Response (201)

{
  "image": {
    "id": "...",
    "parkId": "...",
    "url": "https://...",
    "caption": "Front view of the park",
    "credit": "John Doe",
    "status": "pending",
    ...
  }
}

Suggestions

GET/api/v1/suggestions

List all pending suggestions.

Response

{
  "suggestions": [
    {
      "id": "...",
      "parkId": "...",
      "changeType": "update",
      "changes": { ... },
      "source": "user",
      "status": "pending",
      ...
    }
  ]
}

POST/api/v1/suggestions

Submit a suggestion for a new park or changes to an existing one.

Request Body

Parameter	Type	Required	Description
`changes`	object	Required	Object describing the proposed changes.
`changeType`	string	Required	Type of change, e.g. "update", "new_park", "correction".
`parkId`	string	Optional	ID of the existing park (if updating).
`source`	string	Optional	Source of the suggestion (default: "user").
`sourceUrl`	string	Optional	URL reference for the data source.
`submittedBy`	string	Optional	Name of the submitter.
`email`	string	Optional	Contact email.

Response (201)

{
  "suggestion": {
    "id": "...",
    "changeType": "update",
    "changes": { ... },
    "source": "user",
    "status": "pending",
    ...
  }
}

Cache Revalidation

POST/api/v1/revalidate

Bust the Next.js cache for specific pages or the entire site. Call this after creating or updating parks to see changes immediately.

Request Body

Provide either path or all, not both.

Parameter	Type	Required	Description
`path`	string	Optional	Specific page path to revalidate, e.g. "/denmark/copenhagen/park-name".
`all`	boolean	Optional	Set to true to revalidate all pages.

Examples

// Revalidate a specific park page
{ "path": "/denmark/copenhagen/faelledparken" }

// Revalidate the homepage
{ "path": "/" }

// Revalidate everything
{ "all": true }

Response

// Specific path
{ "revalidated": true, "path": "/denmark/copenhagen/faelledparken" }

// All pages
{ "revalidated": true, "scope": "all" }

iPhone App

The Skateparks.world iPhone app uses its own limited app key in X-API-Key. It can call only the endpoints below plus POST /suggestions; every other endpoint answers 403. Signed-in calls add Authorization: Bearer <access token> from the app sign-in endpoints, and Accept-Language: en or da localizes park text and error messages. Writes are rate-limited per IP address (429 with Retry-After), and suspended accounts get 403 on writes.

Endpoint	Sign-in	Description
`GET /app/status`	No	Service status and the minimum supported app version.
`GET /app/parks/index`	No	Every park, compact. ETag / If-None-Match → 304.
`GET /app/parks/:id`	No	Full park, localized; approved photos only.
`GET /app/parks/:id/ratings?page=1`	Optional	Ratings, newest first, 20 per page. With a token your own rating comes first.
`GET /app/parks/:id/weather`	No	7-day forecast, cached for an hour per park.
`POST /app/reports`	Optional	Report a rating or photo for review.
`POST /app/auth/signup`	No	Create an account (same accounts as the website).
`POST /app/auth/login`	No	Sign in; returns access and refresh tokens.
`POST /app/auth/refresh`	No	Exchange a refresh token for a new session.
`POST /app/auth/logout`	Yes	Revoke the session's refresh token.
`GET / PUT / DELETE /app/profile`	Yes	Read, update or delete the account.
`GET /app/favourites`	Yes	Saved park ids.
`PUT / DELETE /app/favourites/:parkId`	Yes	Save or remove a park.
`POST /app/favourites/merge`	Yes	Merge the phone's saved parks into the account.
`PUT / DELETE /app/parks/:id/rating`	Yes	Create, update or delete your rating (1–5 stars, optional comment).
`POST /app/parks/:id/images`	Yes	Upload a photo; it appears once approved.

Park index (cached on the phone)

GET /api/v1/app/parks/index
X-API-Key: your_app_key
If-None-Match: "etag-from-last-time"

→ 304 Not Modified, or 200 (gzip) with
{ "generatedAt": "…", "parks": [{ "id", "name", "slug", "citySlug", "countrySlug",
  "city", "country", "lat", "lng", "type", "status", "isFree", "sports",
  "hasLights", "averageRating", "ratingCount", "thumbnailUrl" }] }

Notes

Rate limiting

Rating submissions are rate-limited by IP address to prevent abuse.

Image moderation

Uploaded images start with a pending status and require approval before they appear publicly.

Cache behavior

Park pages are statically generated and cached. After creating or updating data, call the revalidation endpoint to see changes reflected on the site immediately.

Content-Type

All endpoints accept and return application/json, except the image upload endpoint which uses multipart/form-data.

Need an API key or have questions?

api@skateparks.world