API & Widget

Thanks for your interest in the nostalgeo API + Widget. Here you can find more information on how to use the API and Widget. Don’t hesitate to contact us to get a free trial access key!

Introduction

The data and imagery collected on the nostalgeo website is accessible through the nostalgeo API or through the nostalgeo Widget. The API can be used to retrieve the URL link to the imagery + the metadata. The Widget consists of a Google Streetview window in which the nostalgeo imagery is positioned on top of Streetview. It is accompanied with a slider, the layout can be fully customized.

General Guidelines

Metadata and/or imagery retrieved from the nostalgeo API/Widget (further referred to as the Content) contains all data you can retrieve from the nostalgeo servers by using the nostalgeo API/Widget.

The Content may be incorporated into your project if:

  • the imagery and/or data is embedded or linked on your website using the HTML and URL provided by nostalgeo
  • the imagery and/or data comes directly from the nostalgeo API

This means that the Content may not be stored locally as such, with exception of the postcard Thumbnails. The thumbnails retrieved via the thumbnailURL can be stored locally.

These solutions ensure that if nostalgeo edits or removes content on its platform in response to user requests, these changes will be reflected in your project too.

Usage of the nostalgeo API/Widget and its Content

Free trial

a free trial of the nostalgeo API/Widget can be requested, please contact nostalgeo through the contact details provided on the website.

Attribution

All uses of the Content must provide attribution to both nostalgeo and its data providers. We require clear, visible attribution when the Content is shown.

If you are unwilling to meet our attribution requirements, contact us directly to inquire about purchasing the rights to use the Content directly. You’ll find our contact details provided on our website.

Hardcopy use

You may not print Content for non- or commercial use.

How to use the nostalgeo API

Connecting to the API

The nostalgeo API can be reached at http://api.nostalgeo.com/

The use of the API requires a "x-client-id" and "x-client-secret". These credentials are provided to you when requesting a free trial.

The client-id and client-secret should be inserted as Headers in the API request:

x-client-id: e.g. “be.nazka”
x-client-secret: e.g. “RsX3KJqOuuENkQH8Sw9iqQUKc7w70EYb”
Content-type: application/json


Postcards requests

The nostalgeo API responds to POST and GET requests.

The POST request is used to make a selection of postcard-id's ("_id"), according to a number of parameters that are specified in the Body of the request.

An individual postcard-id can be used in a GET request to retrieve more information for a specific postcard.

Get a specific postcard

GET: /api/postcards/{postcard_id}

Example response:

{
  "_id": "2Cob4SrCr8HLXmAS5",
  "createdAt": 1445202472786,
  "picture": {
    "url": "https://s3-eu-west-1.amazonaws.com/nostalgeo-storagethumbnails/cropped-postcards/84hMKo57cxnkbA4Lp-XBeumodDy37NrCK3p-kalkstraat.jpg"
  },
  "info": {
    "title": "Kalkstraat",
    "source": "",
    "date": {
      "type": "period",
      "startDate": {},
      "endDate": {}
    },
    "address": "Kalkstraat 40, 9100 Sint-Niklaas",
    "description": ""
  }
}

Description attributes:

_id: unique postcard id
createdAt: date of posting on nostalgeo.com
picture.url: url to resized version of postcard (max res:250 x 250)
info.title: postcard title on nostalgeo.com
info.source: source of postcard
info.date: estimated date/period when the postcard was made
address: address where the postcard was uploaded on nostalgeo.com
description: description of the postcard

Find specific postcards with multiple rules

POST: /api/postcards/find

Supported parameters

All properties can be searched. This means you can search for postcards based on e.g. "_id", "createdAt", "location", "info.address", "creator", "tags" etc. Provide in the body of your request what you’d like to search for. For items to be returned, they must match all the conditions set.

In the example given below, the postcards must:

  • have a tag included called “Kerk”
  • be in the vicinity of the buffer’s coordinates 

{
 
  "tags": {
	"contains": "Kerk"
  },
  "location": {
	"lat": 51.147126999999997565,
	"lng": 4.2989720000000488653
  }
					}

--> Example response

{
  "page": 1,
  "total": 2,
  "count": 2,
  "items": [
    {
      "_id": "H6RPFvnM3W3aDoPRF",
      "createdAt": 1432022172011,
	  "thumbnailURL": https://s3-eu-west-1.amazonaws.com/nostalgeo-storagethumbnails/raw-postcards/DsFK7xsb5ACDr8KSS-02melkerij.jpg
    },
    {
      "_id": "vLupwDamcAmqdYzyR",
      "createdAt": 1432022030576,
	  "thumbnailURL": https://s3-eu-west-1.amazonaws.com/nostalgeo-storagethumbnails/raw-postcards/DsFK7xsb5ACDr8KSS-02melkerij.jpg
    }
  ]
}

The response provides for each postcard that matching the rules tree parameters:

_id: unique postcard id
createdAt: date of posting on nostalgeo.com
thumbnailURL: url to thumbnail of uploaded photo on nostalgeo

However, before retrieving any results, you'll need to supply some parameters first.

Supported options for parameters

equals

Finds all records that matches this string for this property

"creator.username": {
	"equals": "samuel"
	},

is the same as:

"creator.username": "samuel"


gt, lt, gte, lte

Specifically used in combination with "createdAt": used to retrieve postcards based on the post-date on nostalgeo. Date should be entered in Unix Timestamp.

"createdAt": {
	"gte": 1481661600587
	}


like

Finds all records that includes this string for this property; “sam” will match “samuel” and “asamuel”. Query: LIKE %string%

"creator.username": {
	"like": "sam"
	},


contains

The record’s property (array) must contain a certain item. Useful for tags, for example:

"tags": {
	"contains": "Kerk"
	},

or

"tags": {
  "contains": [
	 "Kerk",
	 "Sloot",
  ]
	},


Including geo buffer (proximity)

You can also include the location property with lat and long to get postcards that are in close proximity to the given lat and long. You can also supply a custom accuracy (in km’s) to increase or decrease the search radius around that location.

"location": {
	"lat": 51.147126999999997565,
	"lng": 4.2989720000000488653,
	"accuracy": 0.01
	}


Pagination

By default, if you do not supply the page, you will always request the first page. You can see this in the response:

{
  "page": 1,
  "total": 50,
  "count": 20,
  "items": [
	{
	...

total is the total amount of records that was found for this query. count is how many records are being shown on the current page. You can always request additional pages by adding the page parameter, for example:

POST /api/postcards/find?page=2

or you can include it in the payload as well…

{
  "creator.username": {
	"equals": "samuel"
  },
  "page": 2
	}

Default pagination will return 20 records per page. If you want to customize this amount, please contact nostalgeo through the contact information provided on our website.


How to use the nostalgeo Widget

Include the script file in your code.

<script src="/path/to/nostalgeo.widget.min.js" />

Next, set up the widget at the bottom of your body.

<script>
	var config = {
		client_secret: "fvW1C2JyKJwMSzvNvshMeZvpSgcUewaW",
		postcard_id: "2Wy7GaCaMDgskPc6k"
		selector: "nostalgeo"
	};
	NSGWidget.setup(config);
	// You can enable verbosity if you need to do some troubleshooting.
	// NSGWidget.verbose = true;
</script>
<script async defer src="https://maps.googleapis.com/maps/api/js?key=MAPS_API_KEY"></script>

You need a Google Maps API key to load the Google Streetview window in thet widget. If you don't have one yet, go here to find out more.

Configuration

  • client_secret: The associated secret that has been given so you can use the Widget.
  • postcard_id: The unique identifier of the postcard you want to show.
  • selector: where to show the widget in your application. Searches for this element by id.

Example

See an example of the widget here below (no style applied).

Screenshot Widget

Our Warranties and Disclaimers

We provide our Services using a commercially reasonable level of skill and care and we hope that you will enjoy using them. But there are certain things that we don’t promise about our Services.

OTHER THAN AS EXPRESSLY SET OUT IN THESE TERMS OR ADDITIONAL TERMS, NEITHER NOSTALGEO NOR ITS SUPPLIERS OR DISTRIBUTORS MAKE ANY SPECIFIC PROMISES ABOUT THE SERVICES. FOR EXAMPLE, WE DON’T MAKE ANY COMMITMENTS ABOUT THE CONTENT WITHIN THE SERVICES, THE SPECIFIC FUNCTIONS OF THE SERVICES, OR THEIR RELIABILITY, AVAILABILITY, OR ABILITY TO MEET YOUR NEEDS. WE PROVIDE THE SERVICES “AS IS”. SOME JURISDICTIONS PROVIDE FOR CERTAIN WARRANTIES, LIKE THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. TO THE EXTENT PERMITTED BY LAW, WE EXCLUDE ALL WARRANTIES.

Liability for our Services

WHEN PERMITTED BY LAW, NOSTALGEO, AND NOSTALGEO’S SUPPLIERS AND DISTRIBUTORS, WILL NOT BE RESPONSIBLE FOR LOST PROFITS, REVENUES, OR DATA, FINANCIAL LOSSES OR INDIRECT, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES.

TO THE EXTENT PERMITTED BY LAW, THE TOTAL LIABILITY OF NOSTALGEO, AND ITS SUPPLIERS AND DISTRIBUTORS, FOR ANY CLAIMS UNDER THESE TERMS, INCLUDING FOR ANY IMPLIED WARRANTIES, IS LIMITED TO THE AMOUNT YOU PAID US TO USE THE SERVICES (OR, IF WE CHOOSE, TO SUPPLYING YOU THE SERVICES AGAIN).

IN ALL CASES, NOSTALGEO, AND ITS SUPPLIERS AND DISTRIBUTORS, WILL NOT BE LIABLE FOR ANY LOSS OR DAMAGE THAT IS NOT REASONABLY FORESEEABLE.