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.

Scope Description
read This is the most basic scope and will be included automatically when a user is authorizing your application. This scope entitles to you read any public content on the site (notes, user descriptions, sets, favorites, etc).
readall This scope entitles the application to read not only all public content but also non-public content that the authenticated user can view.
write This scope allows the application to modify content on behalf of the authenticated user. This includes favoriting and unfavoriting, editing and maintaining sets, and so on. The readall scope is automatically included with this scope.
contacts This scope allows the application to follow and unfollow other Findery members on behalf of the authenticated user. The read scope is automatically included with this scope.
notes This scope allows the application to add and edit notes on behalf of the authenticated user. The readall and write scopes are automatically included with this scope.
delete This scope allows the application to delete notes on behalf of the authenticated user. The readall and write scopes are automatically included with this scope.

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.

Prior to authenticating with the API you will need to register your application to get a client_id and a client_secret.

Server-Side Flow

The server-side flow is the most secure and therefore the preferred way of authenticating with the API.

Step One: Redirect the user to request access

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

Query Parameters
  • client_id Required The client ID you received when registering your application.
  • redirect_uri Required The URL to redirect users to after authorizations.
  • response_type Required Must be "code" for the server-side flow.
  • scope A space separated list of scopes. Users may reject requested scopes. If no scopes are specified, the default will be read-only.
  • state An unguessable string. This can be used to prevent CSRF attacks.
Step Two: Findery redirects back to your redirect URL

After the user makes a decision, we will redirect the user back to your site. If the user has accepted your request the request to your site will contain a temporary code parameter as well as the state parameter provided in the previous step. If the states do not match you should not proceed.

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

Step Three: Request an access token

You may now exchange your code for an access token:

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

Body Parameters
  • client_id Required The client ID you received when registering your application.
  • client_secret Required The client secret you received when registering your application.
  • grant_type Required The type of grant you have. This must be "authorization_code" for the server-side flow.
  • code Required The code you received in redirect request above.
Curl Example
      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
    
Step Four: Findery returns a unique access token for user

Findery returns a JSON object including an access_token, scope, and user. You will need to save the access_token and use it when accessing endpoints as the user. See "Accessing Protected Resources" below.

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

Client-Side Flow

The client-side flow, because of its reduced security profile, restricts the scope of access tokens to read-only.

Step One: Redirect the user to request access

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

Query Parameters
  • client_id Required The client ID you received when registering your application.
  • redirect_uri Required The URL to redirect users to after authorizations.
  • response_type Required Must be "token" for the client-side flow.
  • state An unguessable string. This can be used to prevent CSRF attacks.
Step Two: Findery redirects back to your redirect URL

After the user makes a decision, we will redirect the user back to your site. If the user has accepted your request the request to your site will contain an access_token parameter as well as the state parameter provided in the previous step. If the states do not match you should not proceed.

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

Accessing Protected Resources

The access token allows you to make request on the user's behalf. The access token should be sent in the Authorization header.

Authorization: Bearer ACCESS_TOKEN

Using curl:

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.

Status Code Error Explanation
400 Bad Request Usually this means that you are missing a required query parameter or field in the POST body on your request.
401 Unauthorized The request is missing authentication information in the form of an access token or authorization code. You may not have included your client_id or an access token in the request.
403 Forbidden You are not authorized to access the information requested with the authentication used.
404 Not Found The requested resource was not found.
429 Too Many Requests You are currently being rate limited. Check the X-Rate-Limit-Resets-At header to see when you can make more requests.
500 Internal Error Something has gone wrong on our end. If you see this, please report it to us by emailing us at help@findery.com.