Findery API

At Findery, we love sharing interesting stories about places around the world. Up until now, the only way to join the party was through Findery.com or our apps.

Now there’s a backstage pass with the Findery API.

Using the Findery API, developers can integrate with Findery. Create Findery notes for any location, gather notes into collections (we call them notemaps), and discover interesting places nearby. The Findery API is free and includes endpoints for notes, notemaps, comments, users, following, and more.

What can I do with the API?

With the Findery API, you can take advantage of our great content, near and far. Get nearby notes for local discovery, tourism, or the awesome tidbits you won’t find in history books. Display notes about your business to show how much customers love you. Create a notemap full of hidden treasures to visit. We look forward to finding new uses for Findery!

How do I get started?

The Findery API is free and easy. If you have experience with APIs, you should feel right at home. The Findery API implements the OAuth 2.0 standard for secure authentication and authorization and uses SSL for communication.

Get started by registering your app. It only takes a few minutes. Feel free to ask us questions on Stack Overflow.

By using the API, you agree to our Terms of Service, the Community Guidelines, and the Findery Public API Terms of Use.

The first step is to create a Findery account if you don't already have one. Next you want to register your application. You will be redirected to the login page if you are not logged in. After registration, we will generate a unique client ID and secret for your application. The client ID represents the public identifier for your application but the client secret must be kept secure and private, as this would allow anyone to authenticate users posing as your app. If this secret is ever compromised, we require that you regenerate the secret to your application by clicking the "regenerate secret" button on your application's page.

Your application will also require a redirect URL, which is the callback that we will send users to after they accept or deny your authorization request. This URL can be either SSL or not (that is, either http or https) but we encourage SSL for all authorization steps.

Authorizing Users

If you only want to fetch public content—say public notes tagged Wilkes County or burrito— the basic scope of 'read' will suffice. But if you want to access non-public content or act on the behalf of the user to modify resources, the user will need to authorize your application with extra permissions. After the user has authenticated with us and authorized your application, you'll receive an access token identifying that user. To run an API call on behalf of a user, just include the user's access token with the request.

Authorization Flows

We provide two flows to let Findery members authorize your application (which will be explained below), but both flows begin by pointing the member to a specially-formed URL on Findery, which lets us identify the member, as well as allow you to pass in any extra permissions you'd like the user to approve. On your application page, we've pre-generated authorization URLs specific to your application. This URL, combined with the scope and state parameters, is where you will send the user (by click or redirect) in order for them to authorize your application.

For both flows, the state parameter is optional. If it's included in any of the authorization flow requests, it will be included in all responses. We suggest using this parameter so that you can ensure that any callbacks to your application originated from your application.

The scope parameter consists of a space-delimited string specifying what level of access your application requires. The scopes are listed and explained below.

It is always best to ask for as few permissions from Findery members as possible. Asking for less than you need not only increases the member's trust in your application, but also keeps the impact of leaking access tokens and programming errors to a minimum.

GET https://findery.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_url=YOUR_REDIRECT_URL&scope=notes contacts delete

GET https://example.com/redirect/path?code=CODE&state=STATE

POST https://findery.com/oauth/access_token

      curl --data "grant_type=authorization_code&code=YOUR_CODE_FROM_REDIRECT&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"  https://findery.com/oauth/access_token
    

{"access_token":"34njk3dNS3XEKNTWO3j5334jn53o32n4l3k4n36o3nNek2n1NXl349","scope":"write","user":{"id":1090921732141,"username":"john"}}

GET https://findery.com/oauth/authorize

GET https://example.com/redirect/path?access_token=ACCESS_TOKEN&state=STATE

Authorization: Bearer ACCESS_TOKEN

curl -H "Authorization: Bearer ACCESS_TOKEN" https://api.findery.com/v2/users/743030428577

In order to make any authenticated call to the API, pass the access token you received for a user from one of the above authorization flows along with any of the requests. Sending the access_token can be done by either URL query parameters or by a form field for non-GET statements.

Peruse our many API endpoints that allow you fetch existing notes and add new ones, follow other members, and generally explore the site in a rich programmatic way. The docs include a cURL example for every method we support to make it easier to get started.

We rate API calls at 100 queries in 10 minutes. We'll return a 429 status code if you're being throttled with a message of when you can try again.

We try our best to provide errors with appropriate HTTP status codes whenever possible.