API

The Sourcemap API makes it easy to share supply chain information across platforms. Anyone can use the API to read publicly available information from Sourcemap.com. In order to create maps on Sourcemap.com using the API, please contact us to receive your api key and api secret.

You can download an API client for PHP and Javascript here. We've also made available some small demo apps that demonstrate grabbing data from Sourcemap and doing different things with it locally. These apps use javascript to access supplychains as json and geojson objects.

License

When using the Sourcemap API, you agree to be bound by the API Terms of Service.

Overview

The Sourcemap API provides web services for developers to interact with Sourcemap data, users, maps, and tools. Where possible, the services adhere to REST principles. In general, services are accessed at pathnames beginning with services/. Data is accessed with or without authentication using the HTTP methods GET, PUT, POST, and DELETE.

A simple "discovery" service exists at the base services url /services/.(http://sourcemap.com/services/)

curl -is http://sourcemap.com/services/

The above command will yield JSON (other serialization formats are available) like the following.

HTTP/1.1 200 OK Date: Mon, 1 Jan 2099 18:50:37 GMT Content-Length: 50 Content-Type: application/json {"services":["search","supplychains"],"you":false}

Authentication

Authentication for the Sourcemap API centers around tokens generated using an API key-secret pair. The key is generated randomly and assigned on request. Since we don't currently support three-party authentication, you can only use the API to get public data or private data that belongs to you using key-secret authentication.

To use your API key, you will need to construct a few special HTTP headers for every request you'd like to authenticate. Every authenticated API request requires the Date header. The date is expected to be in RFC2822 format. This date should match the date and time on the Sourcemap servers to within 30 seconds. The API key should be included in the special HTTP header X-Sourcemap-API-Key.

The final header required for authentication with the Sourcemap API is the X-Sourcemap-API-Token header. It is constructed by concatenating the values of the Date header, the API key, and the API secret then hashing them using the md5 algorithm, widely available in the most popular scripting languages. This could be done in PHP as follows, assuming $date, $apikey, and $apisecret are properly set:

$apitoken = md5(sprintf('%s-%s-%s', $date, $apikey, $apisecret));

Supplychains

Native Sourcemap objects are called supplychains, and they consist of Stops (points on a map) and Hops (the lines connecting those points).

Supplychain Properties

  • id – A unique incremental id representing the supplychain.
  • title – The title of the supply chain.
  • other_perms – Permissions for the supply chain (this is not a property of the attributes array, but a top level supply chain property). Set this property to 1 to create public (rather than private) supply chains

Stop Properties

  • id – A unique incremental id representing the stop.
  • title – Add the name of the source as you want it to appear in the map bubbles.
  • placename – Insert the place name for the source.
  • address – Enter specific address, this will be the Geocode used for the mapped location.
  • description – Type the text description of the source here. Can be a fact about procurement, the product, the region, etc.
  • percentage – Proportion of Total Volume. Enter the percentage of total sourcing volume coming from this source. This can be the percentage of weight/volume/etc ofthe total product or percentage that this location represents.
  • color – This will be the color of the Stop. Choose different colors to represent different layers, facts, or other variable.
  • size – Manual size entry for the stop (in pixels)
  • qty – Number of units.
  • unit – Units, like kg or ea (eaches).
  • weight – Weight per unit, if other then kg.
  • co2e – Impact factor (co2e) of the source.
  • urltitle:moreinfo – A name for the link to more information on the source.
  • url:moreinfo – A link for more information on the source.
  • youtube:title – The title for the youtube video.
  • youtube:link – The link to a youtube movie to be embedded.
  • flickr:setid – The flickr setid to be embedded.
  • vimeo:title – The title for the vimeo video.
  • vimeo:link – The link to a vimeo movie to be embedded.

Hop Properties

  • from – The id of the stop the hop is coming from.
  • to – The id of the stop the hop is going to.
  • description – Type the text description of the transport here. Can be a fact about procurement, the product, the region, etc.
  • color – This will be the color of the Hop. Choose different colors to represent different layers, facts, or other variables.
  • transport – Transport type (like "Air Freight (Regional)")
  • qty – Number of units traveling.
  • unit – Units, like kg or pax (for personal travel).
  • distance – Distance traveled, if not calculated automatically.
  • co2e – Impact factor (co2e) of the transport type.

Reading Supplychains

The supplychains service provides an endpoint for fetching lists of public supplychains. You can set the limit and offset values using the query string parameters l and o, respectively. You can use the f parameter to specify the formatting for the return object. The default value is json, but if you needed to access the api in javascript, for example, you could request jsonp. Other format include csv, geojson, kml, or php. http://sourcemap.com/services/supplychains/?l=10&o=25

curl -is 'http://sourcemap.com/services/supplychains/?l=10&o=25' { "supplychains":[ {"id":27,"created":1300813400}, {"id":28,"created":1300908605}, {"id":29,"created":1300912711}, {"id":30,"created":1300913070}, {"id":31,"created":1302014532}, {"id":32,"created":1302014685}, {"id":33,"created":1302014775}, {"id":34,"created":1302889435}, {"id":35,"created":1302890553}, {"id":36,"created":1302890575}, ], "total":128, "limit":10, "offset":25 }

The supplychains endpoint isn't a good method for finding supplychains based on their attributes. This is better accomplished using our search services.

Individual supplychains may be accessed using paths of the form services/supplychains/[id] where [id] is a supplychain ID.

http://sourcemap.com/services/supplychains/219

curl -is 'http://sourcemap.com/services/supplychains/219'

Would return the following:

HTTP/1.1 200 OK Date: Mon, 1 Jan 2099 19:59:55 GMT Content-Length: 1515 Content-Type: application/json { "supplychain":{ "category":null,"created":1298652652, "flags":32,"id":1,"modified":1306106036, "other_perms":1,"usergroup_id":null, "usergroup_perms":0,"user_id":234, "owner":{ "id":444,"name":"somefakeuserguy", "avatar":"http:\/\/www.gravatar.com\/avatar\/..." }, "taxonomy":null, "attributes":{}, "stops":[ { "local_stop_id":5,"id":5,"geometry": "POINT(-9349165.430522 4044184.943345)", "attributes":{ "name":"Facility #5" } },{ "local_stop_id":4,"id":4,"geometry": "POINT(-10634992.255936 3485526.892738)", "attributes":{ "name":"Facility #4" } },{ "local_stop_id":3,"id":3,"geometry": "POINT(-12489606.041822 3954200.282625)", "attributes":{ "name":"Facility #3" } },{ "local_stop_id":2,"id":2,"geometry": "POINT(-7929147.678904 5239202.289146)", "attributes":{ "name":"Facility #2" } },{ "local_stop_id":1,"id":1,"geometry": "POINT(-10804007.180522 3869332.593955)", "attributes":{ "name":"Facility #1" } } ], "hops":[ { "from_stop_id":3,"to_stop_id":1, "geometry": "MULTILINESTRING((-12489606.041822 3954200.282625, -10804007.180522 3869332.593955))", "attributes":{} },{ "from_stop_id":3,"to_stop_id":2, "geometry": "MULTILINESTRING((-12489606.041822 3954200.282625, -7929147.678904 5239202.289146))", "attributes":{} },{ "from_stop_id":3,"to_stop_id":4, "geometry": "MULTILINESTRING((-12489606.041822 3954200.282625, -10634992.255936 3485526.892738))", "attributes":{} },{ "from_stop_id":3,"to_stop_id":5, "geometry": "MULTILINESTRING((-12489606.041822 3954200.282625, -9349165.430522 4044184.943345))", "attributes":{} } ] },"editable":false }

Data Formats

These examples show results in the default format (json). Other formats can be requested using the f paramater. Available formats include:

[json|jsonp|geojson|php|form|kml|csv|xls|xlsx]

As an example, http://sourcemap.com/services/supplychains/1679?f=kml prompts a download of map 1679 in Google Earth's KML format.

Search

The simple search feature allows API consumers to search supplychains by keyword and/or category.

HTTP/1.1 200 OK Date: Mon, 1 Jan 2099 20:15:11 GMT Content-Length: 432 Content-Type: application/json { "search_type":"simple","offset":0,"limit":25, "hits_tot":1,"hits_ret":1, "parameters":{ "q":"texas" }, "results":[ { "category":null,"created":1300738955,"flags":0, "id":26,"modified":1300738995, "other_perms":1,"usergroup_id":null, "usergroup_perms":0,"user_id":1, "attributes":{ "name":"BSR2010" }, "owner":{ "created":1298652655,"id":1,"last_login":1307583315, "logins":40,"username":"administrator", "name":"administrator" } } ], "cache_hit":true}

Projection Conversion

Supply chains expect to be given Well Known Text formatted points (for stops) and multiline strings (for hops). These are not latitude and longitude coordinates, but EPSG:900913 coordinates. We provide a goecoding service that will be helpful in converting to this projection. For example:

http://www.sourcemap.com/services/geocode/?ll=-71.1097,42.3726

curl -is 'http://www.sourcemap.com/services/geocode/?ll=-71.1097,42.3726'

Where ll is the longitude,latitude of the point.

Creating and Updating

After authenticating with an API Key, you can post a supplychain json description to the supplychains service. Similarly you can update an existing supplychain by put-ing a json file describing the supplychain to the id of the supplychain you wish to update. If you have a Sourcemap API key and would like to try using the write api, the best starting place is in the SrcClient php library. example.php contains detailed examples of creating, updating, and viewing created supply chains.

Viewing Sourcemaps

Sourcemap Embeds

Sourcemap embeds are simple iframe style embed codes that can be safely placed on another site. They look like:

<iframe width="640px" height="480px" frameborder="0" src="http://www.sourcemap.com/embed/1679"></iframe>

And the width and height are recommended, but not required settings. To embed a different map, just changed the requested id number at the end of the request, like this:

http://www.sourcemap.com/embed/[map_number]

Different options can be passed to the embed, currently available options are:

  • served_as – [default|static]

Shortened URLs and QR Codes

You can request shortened urls (http://srce.mp) with the request:

http://sourcemap.com/services/shorten/?url=http://www.sourcemap.com/view/[map_number]

For example http://sourcemap.com/services/shorten/?url=http://www.sourcemap.com/view/1679 Returns the short url http://srce.mp/zvgatT

Two dimensional barcodes (QR Codes) are also available, although you will have a significantly better result using the shortened link as the paramater. To request a qr code, you can make the reqest:

http://www.sourcemap.com/services/qrencode?q=[url_encoded_shortlink]&sz=[size]

Size can be any value [1-10] but the default setting of 3 is recommended. The request http://www.sourcemap.com/services/qrencode?q=http%3A%2F%2Fsrce.mp%2FzvgatT&sz=3 returns the qr code for map 1679, using the url encoded shortlink.

Static Maps

Static maps are available for Sourcemaps using the static map service. For example, the fullsize static map for map 1438 is available at:

http://www.sourcemap.com/static/1438.f.png

The preferred mechanism for using static maps is to access them through a standard Sourcemap iframe embed:

<iframe width="710px" height="310px" frameborder="0" src="http://www.sourcemap.com/embed/1438?served_as=static"></iframe>

In circumstances where you are unable to use an iframe embed, you may request the image directly from the /static/ service, but we prefer that you wrap this in a link back to the originating sourcemap.

<a href="http://www.sourcemap.com/view/1438/"><img src="http://www.sourcemap.com/static/1438.f.png" /></a>

The static service is available in the format:

http://www.sourcemap.com/static/[map_number].[size].png

Maps can be accessed in a variety of sizes. Possible sizes include:

  • [s] – small – 160px x 98px
  • [t] – thumbnail – 160px x 105px
  • [m] – medium – 220px x 128px
  • [l] – large – 710px x 310px
  • [f] – fullsize – 1032px x 560px

Image sizes are approximately, and will vary depending on the composition of the map. Also, because the static map service draws maps with a slightly different process than the dynamic map, the maps will tend to differ slightly from dynamic drawings.