Getting Started

Endpoints

Reference

Guide page blocks

An experience's guide pages hold their content as a list of blocks. The guide page endpoints read and write the same list: a page you read and send back unchanged keeps its content, except for the limits listed at the end of this page.

// POST https://ridewithgps.com/api/v1/experiences/1/guide_pages.json
{
  "guide_page": {
    "title": "Day 1 - Florence to Siena",
    "blocks": [
      { "type": "text", "markdown": "## Morning\nLeave the hotel at **8:30**. Coffee stop in [Greve](https://example.com)." },
      { "type": "photo", "photo_id": 20800253, "on_tap": "enlarge" },
      { "type": "route", "route_id": 123 },
      { "type": "elevation_profile", "route_id": 123 },
      { "type": "text", "markdown": "- Water at km 40\n- Lunch in Castellina" }
    ]
  }
}

Block types

type Fields you send Fields added when you read
text markdown
photo photo_id, on_tap (none, enlarge or open_link, default none), link_url (with open_link) url of the image
route route_id name, distance and elevation_gain (meters) shown on the route card
elevation_profile route_id

Photos must belong to your organization. Upload an image with POST /api/v1/photos and use the returned id as photo_id; use it in a page within 24 hours, because photos that nothing uses are deleted after that and a later save that names them gets a 422. A page made in the web editor may show a photo owned by someone else; remove or replace that photo before saving the page through the API. Routes must belong to your organization too, except a route the page already used, which stays accepted. Any other id is refused with a 422 that does not say whether the photo or route exists.

Fields added when you read are ignored when you send them back.

link_url and links in text must start with http://, https://, mailto: or tel:.

Markdown in text blocks

A blank line starts a new paragraph. Each additional blank line adds an empty paragraph, which shows as extra space in the app.

Write For
# Title, ## Title, ### Title Headings. Deeper headings become ###.
**bold** Bold
*italic* Italic
<u>underline</u> Underline
[text](https://example.com) Link. Bold, italic and underline work inside the text.
- item, * item or + item Bullet list item
1. item or 1) item Numbered list item. The app numbers the items itself.
---, *** or ___ alone on a line Separator line
a single line break Stays inside the same paragraph or list item. The app shows it as a space.

Put a backslash before a character to write it as text: \*, \[, \], \\, and \<u>. A * or <u> without its closing pair is written as text. When you read a page, these characters come back with their backslash, and a line that would read as a heading, list item or separator starts with a backslash: \# not a heading.

Other HTML tags, such as <b>, are not supported and are kept as plain text. Underscores (_text_), code, quotes, tables and images in Markdown are not supported either and are kept as plain text. Use a photo block for images.

Limits

These parts of a page made in the web editor are not kept when the page is read and sent back:

  • Nested list indents. Indented list items become top-level list items. Indenting a list item in Markdown does not nest it either.
  • Line breaks at the start or end of a paragraph, and a blank line inside a paragraph, which becomes two paragraphs. The app shows line breaks as spaces, so this rarely changes how a page looks.