Geochron API

Authentication

Your account is assigned an API key, which must be sent as a key query string parameter in all requests to the API.

To view your API key, sign-in to the interface and view your Account details in the top-right.

Layer Operations

Base URL: https://interface.geochron.com/api/layers

Create, modify, or destroy your custom layers.

POST: /create

Creates a new layer of given type and name.

NOTE: Only "Fixed" is currently accepted as a layer type.

Request

{
  "Name": "My New Layer",
  "Type": "Fixed"
}

Name	Type	Description
Name	string	New Layer Name
Type	string	New Layer Type (Fixed)

Response

{
  "Name": "My New Layer",
  "Type": "Fixed"
}

Name	Type	Description
Name	string	New Layer Name
Type	string	New Layer Type (Fixed)

GET: {id}/delete

Delete layer {id} immediately.

POST: /{id}/rename

Accepts a Rename Request with a new layer name and attempts to rename layer {id}.

Component Operations

Base URL: https://interface.geochron.com/api/layers/{layerID}/component/{componentName}

Create, modify, or destroy layer components.
Trigger life-cycle events for components

GET: /

Fetch raw component JSON configuration.

POST: /

Immediately set raw component JSON configuration.

POST: /update

Merge supplied POST body JSON object with existing raw component JSON configuration.

Request/Response

{
  "Type": "Point",
  "Label": "Test Point",
  "Lat": 43,
  "Lng": -122.0,
  "Color": "#ffffff",
  "Icon": null
}

{
  "Lat": 43.0,
  "Lng": -122.0
}

GET: /delete

Delete component immediately

POST: /rename

Accepts a Rename Request with a new component name and attempts to rename the component.

POST: /process

Accepts arbitrary binary POST data and triggers the processing phase of a component life-cycle.
Returns no response.

This is most useful for image components: Overlays, Legends, and Http types - the POST data is assumed to be a PNG image and is stored on the server, and the appropriate component parameters are updated immediately.

Component Structures

Components are represented as JSON objects with a mandatory Type key.

Point

{
  "Type": "Point",
  "Label": "My Point",
  "Color": "#ffaa00",
  "Lat": -43.2,
  "Lng": -122.0,
  "Icon": null
}

Name	Type	Description
Type	string	Mandatory type name
Label	string	Text label, printed above and to the right of the point
Color	string	Hex color code
Lat	decimal	Latitude within expected ranges
Lng	decimal	Longitude within expected ranges
Icon	icon	Custom icon (optional)

Path

{
  "Type": "Path",
  "Points": [
    { "Lat": -43.2, "Lng": -122.0 },
    { "Lat": -45.0, "Lng": -125.0 },
  ],
  "Color": "#ffaa00"
}

Name	Type	Description
Type	string	Mandatory type name
Points	lat-lng-list	List of points to draw the path along
Color	string	Hex color code

Overlay

{
  "Type": "Overlay",
  "ImageURL": "http://storage.geochron.com/7d/7debe3be98c7fff3b6a68862a4ef1080bf69b53e274b8f9faefb141ca2b7cda5.png",
  "ImageTime": 0,
  "ImageHash": "7debe3be98c7fff3b6a68862a4ef1080bf69b53e274b8f9faefb141ca2b7cda5",
  "Layer": "Over"
}

Name	Type	Description
Type	string	Mandatory type name
ImageURL	url	URL to the image to use as an overlay
ImageTime	int	Last time the image was uploaded (or 0, if never or not applicable)
ImageHash	string	Content hash of the image (see hashing)
Layer	string	Location of the overlay relative to the shaded night portion of the map ("Over", "Under")

Legend

{
  "Type": "Legend",
  "ImageURL": "http://storage.geochron.com/4c/4ce75bcd8bdc9765dfbd17c18d872f7c8049cb1101c537e0b652d075c5830d4a.png",
  "ImageTime": 0,
  "ImageHash": "4ce75bcd8bdc9765dfbd17c18d872f7c8049cb1101c537e0b652d075c5830d4a",
  "Position": "Left"
}

Name	Type	Description
Type	string	Mandatory type name
ImageURL	url	URL to the image to use as a legend
ImageTime	int	Last time the image was uploaded (or 0, if never or not applicable)
ImageHash	string	Content hash of the image (see hashing)
Position	string	Position of legend on device screen ("Left", "TopLeft", "Top", "TopRight", "Right", "BottomLeft", "BottomRight")

Orbital

{
  "Type": "Orbital",
  "Label": "Intl. Space Station",
  "Color": "#ffaa00",
  "TLE1": "1 25544U 98067A   20220.82748236  .00001293  00000-0  31444-4 0  9991",
  "TLE2": "2 25544  51.6459  92.8834 0000920  20.3968  59.5056 15.49153310240025",
  "Icon": null
}

Name	Type	Description
Type	string	Mandatory type name
Label	string	Text label, printed above and to the right of the satellite
Color	string	Hex color code
TLE1	string	First line of a Two-Line Element (TLE) component
TLE2	string	Second line of a Two-Line Element (TLE) component
Icon	icon	Custom icon (optional)

Location

{
  "Type": "Location",
  "Label": "Oregon City",
  "Color": "#ffaa00",
  "LocType": "PostalCode",
  "LocData": "97045"
}

Name	Type	Description
Type	string	Mandatory type name
Label	string	Text label, printed above and to the right of the point
Color	string	Hex color code
LocType	string	Only "PostalCode" is supported currently.
LocData	string	Postal Code of desired location.

HTTP

{
  "Type": "Http",
  "Purpose": "Overlay",
  "FetchURL": "http://example.com/worker/fetch",
  "RenderURL": "http://example.com/worker/render",
  "Expiry": 3600,
  "StaticConfig": {
    "CustomRendererProperty": "CustomValue",
    "Color": "#ffffff"
  }
}

Name	Type	Description
Type	string	Mandatory type name
Purpose	string	Either "Overlay" or "Legend"
FetchURL	url	URL of 'fetch' script to call to retreive component data
RenderURL	url	URL of 'render' script to call to begin the render process
Expiry	int	Time (in seconds) before the layer should be considered 'stale'
StaticConfig	string	JSON configuration to be passed to the render worker via the Config key.

CSV

{
  "Type": "Csv",
  "Data": "Point,Test Point,45.0,-122.0,#ff0000
Location,PostalCode,97045,Oregon City,#ffaa00"
}

Name	Type	Description
Type	string	Mandatory type name
Data	string	CSV-formatted components

Special Structures

Special structures are used to represent certain component properties or certain data-types.

Icon

Used anywhere an icon is supported (Point, Orbital, Location). null is accepted instead of the icon structure if no icon is desired.

{
  "IconURL": "http://storage.geochron.com/cb/cb1e315b2e99b417a1ac5ecead4c79f01d47eb455b23010747749a27d362edbc.png",
  "IconHash": "cb1e315b2e99b417a1ac5ecead4c79f01d47eb455b23010747749a27d362edbc"
}

Name	Type	Description
IconURL	url	URL to the image to use as an icon
IconHash	url	Content hash of the image

Lat/Lng List

An unindexed, ordered array of lat/lng pairs.

{
  "Points": [
    { "Lat": -43.2, "Lng": -122.0 },
    { "Lat": -45.0, "Lng": -125.0 },
  ]
}

Name	Type	Description
Points	array of lat-lng	JSON array of lat/lng pairs

Lat/Lng

Represents a pair of latitude & longitude values that resolve to a point.

{
  "Lat": -43.2,
  "Lng": -122.0
}

Name	Type	Description
Lat	decimal	Latitude within expected ranges
Lng	decimal	Longitude within expected ranges

Entity Rename Request

Sent to a rename REST endpoint to change the name of a layer or component.

{
  "NewName": "My New Name"
}

Name	Type	Description
NewName	string	New name of the layer or component

Entity Rename Response

Received as a response to a command that renames a component or a layer.

{
  "Successful": true,
  "OldName": "Old Boring Name",
  "NewName": "My New Name"
}

Name	Type	Description
Successful	bool	Indicates success of rename.
OldName	string	The name the layer or component used to have
NewName	string	The name the layer or component now has - should match the supplied name (but may not)

JSON HTTP REST API