Arrivedo Documentation

Javascript library reference

arrivedo.js

A collection of methods and styles to integrate our API in your website in very few lines of code.

To use it, you can include it from our public CDN like so:

<script src="https://res.arrivedo.com/arrivedo.js"></script>

This script exposes the following classes to the main scope:

ArrivedoClient

The main class, it has methods that allow you to fetch and display content from arrivedo API or a JSON source, create maps and display these articles

If you choose to use the fetch methods (meaning you are not using Arrivedo API in your server but in the browser), you have to provide your Arrivedo Public Key

If you use the map shortcuts you have to provide your Mapbox Access Token

  new ArrivedoClient(options)


Parameters (options)

All parameters are optional

Name Description
options.arrivedo_key (String) Your Arrivedo Public Key
options.mapbox_access_token (String) Your Mapbox Acces Token
options.mode (String) Indicates whether the application is running in 'production' or 'testing'. Default is 'production'
options.language (String) Indicates language in which article data will be displayed if article exists in such language. Default is 'en'
options.custom_colors (Object) Indicates custom colors for the article places that are displayed from ArrivedoClient.renderArticleBody
options.custom_colors.primary (String) A valid color of the primary places.
Default looks like this: 1 Pariwana Hostel Lima
options.custom_colors.optional (String) A valid color of the optional places.
Default looks like this: Larcomar
options.custom_colors.active_primary (String) A valid color for the primary places that are targeted at the article body.
Default looks like this: 1 Pariwana Hostel Lima
options.custom_colors.active_optional (String) A valid color for the optional places that are targeted at the article body.
Default looks like this: Larcomar


Instance methods

getArticle(slug)

Obtain a single article from Arrivedo API

Parameters:

Slug: (String) The article slug identifier.

Returns:

(Promise) A promise that resolves with JSON formatted article.

getArticleList(slug, lang)

Obtain a list of articles from Arrivedo API

Parameters

slug (String) The organization slug identifier.

lang (String) The language for the article (default is ‘en’).

Returns

(Promise) A promise that resolves with JSON formatted list of articles.


renderArticleBody(article, dom_object, options)

Display an article in the given dom object

Parameters

article (Object) Article object as obtained from Arrivedo API or JSON, receives input from getArticle(slug)

dom_object (DOM OBject) A DOM object to place the content into.

options.place_numbers (Boolean) A flag indicating wehther to display numbers before each place inside the article body, to make it easier for readers to match mentioned places and map pins.

createArticleCard(article)

Creates an artile card, a shortcut for HML markup

Parameters

article (Object) Article object as obtained from Arrivedo API or JSON, receives each member of the array returned by getArticleList(slug)

Returns

(String) An HTML string describing a formatted article card.

createMap(container, options)

Creates a map and puts it in specified container, this method also loads all Mapbox assets in case they were not loaded previously

Parameters

container (DOM Object | String) A DOM object or an element’s ID

options.custom_map_style (String) A string specifying the URL of the custom Mapbox Style to load if any.

options.center (Array) An array that specifies where the map will be initially centered. Default value is [0,0]

options.zoom (Number) Zoom level between 0 and 24 (where 0 is the entire globe). Default value is 3;

options.clusters (Boolean) A flag that specifies if pins should be grouped when optional places are detected in an article. Default is true.

options.display_on_data (Boolean) A flag that specifies map should display only when data is provided, (this prevents flickering if you want your map to load an article directly as the user arrives as an example)

options.custom_colors (Object) Object with valid hex colors for the customizable components of the map, see Arrivedo Map for specific details.

options.zoom_control (Boolean) Flag that specifies if map should display with zoom-in/zoom-out navigation helper. Default is True

Returns

(Promise) A promise that resolves with an Arrivedo Map object.

bindMapToScroll(scroll_element, map)

Syncrhonizes scroll with map centering for places on display, so visible (not hidden by scroll) places within the text container, are displayed on the map as user scrolls down or up.

Parameters

scroll_element (DOM Object) The DOM element that scrolls down the content.

map *(Object)** An Arrivedo Map object you want to synchronize.





MapManager

An instance of this class is produced and returned by ArrivedoClient createMap() method, you can also use it independently

  new MapManager(container, mapbox_key, mapbox_map_style, options)


Parameters (options)

Name Description
container (Object|String) Either a DOM Object or a valid ID (String) of a DOM element
mapbox_key (String) Your Mapbox Acces Token
mapbox_map_style (String) Your Mapbox style URL
options.center (Array) A latitude,longitude array to center your map in, default is [0,0]
options.zoom (Number) Zoom level between 0 and 24 (where 0 is the entire globe), default is 3
options.clusters (Boolean) A flag that specifies if pins should be grouped when optional places are detected in an article, default is true
options.display_on_data (Boolean) A flag that specifies map should display only when data is provided, (this prevents flickering if you want your map to load an article directly as the user arrives as an example), default is true
options.custom_colors (Object) Indicates custom colors for the article places displayed at the map from MapManager.displayArticle
options.custom_colors.primary (String) A valid hex string color of the primary places.
Default looks like this:  1
options.custom_colors.optional (String) A valid hex string color of the optional places.
Default looks like this: 
options.custom_colors.active_primary (String) A valid hex string color for the primary places targeted at the map.
Default looks like this:  1
options.custom_colors.active_optional (String) A valid hex string color for the optional places targeted at the map.
Default looks like this: 
options.custom_colors.path_color (String) For articles with routes, paths will display with this color (hex string), default is '#1cb2fa' 
options.custom_colors.active_path_color (String) Color of active paths in the map. Same color is use as background of map message. Default is '#1f6dc7' 
options.custom_colors.path_width (Number) For articles with routes, paths will display with this thickness. Default is 4
options.custom_colors.path_opacity (Number) For articles with routes, paths will display with this opacity. Default is 1
options.zoom_control (Boolean) Flag that specifies if map should display with zoom-in/zoom-out navigation helper. Default is true


Instance properties

mapbox_map

The original map object that Mapbox creates


Instance methods

loadPromise()

Produces a promise that resolves when the map is completely loaded, so you can proceed to call other methods in this map.

Returns

(Promise) A promise that resolves when all map assets and styles are loaded

displayArticle(article, options)

Displays all the places mentioned within an article as pins in the map instance.

Parameters

article (Object) Article object as obtained from Arrivedo API or JSON, receives input from getArticle(slug)

options.place_numbers (Boolean) A flag that specifies if places should be numbered. Default is true

options.custom_class (String) A custom className for every pin created in this call

options.route_banners (String) Flag that specifies if start and end of route banners should appear. Only applies to route articles. Default is true

centerPlaces(places, options)

Zooms and pans the map to fit the provided set of places.

Parameters

places (Array) An array of places as Arrivedo API provides them (as a result of calling getArticle() or getArticleList())

options.method (String) Either ‘panning’ or ‘flying’. Default ‘panning’.

options.duration (Number) Number of miliseconds for the transition. (default 600)

options.padding (Number) Pixels to leave as a padding space between map borders.

refresh(update_center,options)

Puts map back to its original state after user manipulation.

Parameters

update_center (Boolean) Wether to update map center or not. Default false.

options.duration (Number) Number of miliseconds for the transition. (default 300)


Errors

Arrivedo uses traditional HTTP response codes to specify if the call is successful or a failure occurred.


Response status codes Description
200 - OK Successful call.
401 - Unauthroized/Authentication Error There was an error with the authentication or a method that requires an ArrivedoClient with a valid arrivedo_key to be created is being called.
403 - Forbidden The arrivedo_key provided does not has permissions to perform such request.
404 - Resource not found The requested resource does not exist.
422 - Unprocessable Entity There was an error with the parameters.
424 - Mapbox Error An error with Mapbox API ocurred.
500 - Server Error Something went wrong on Arrivedo's API.
503 - Network Error There was an error trying to connect with Arrivedo's API


Every arrivedo error has the following structure

Attributes Description
type (String) The type or error returned, can be one of: authentication_error, forbidden_error, api_error, not_found, mapbox_load_error, invalid_request_error, arrivedo_unauthorized_error
code (Number) HTTP response code
message (String) Human-readable message with more insight about what the error was.


Error Types Description
authentication_error An error occured while trying to authenticate with Arrivedo's API, please verify that the provided arrivedo_key is correct or you can check the documentation for how to properly authenticate ArrivedoClient.
forbidden_error The Arrivedo key provided is not a member of the organization or has no access to the article. Please contact the organization administrator.
api_error There was an error with Arrivedo's API, please contact us at apisupport@arrivedo.com
not_found The requested resource was not found at Arrivedo's DB, please verify that the 'article_slug' or 'organization_slug' is correct.
mapbox_load_error An error ocurred when trying to create Mapbox's Map, more info will be found at the error's message. You can also check the documentation for the map.
invalid_request_error The parameters for the request are invalid, please check that you are providing the right parameters.
arrivedo_unauthorized_error The ArrivedoClient was not created with an arrivedo_key and a fetch method is trying to be used.


Every time an error ocurrs the ArrivedoClient will throw an error, we encourage writing code that graciously handles all possible errors described above.