Posts

Locations

location-service

Locations posts can be tied to: placed on a map, or found from an address, and the posts tied to each.

Locations

GET/locations/

Found by words, near a point, or the locations one post is tied to.

Who: Anyone, signed in or not

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
qstringin query
Words its name or address holds. At most 100 characters.
sortstringin query
The order they come in. At most 10 characters. One of popular, trending, recent, name. recent unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
source_idintegerin query
Only the places a post is tied to: the post's id.
nearby_latitudenumberin query
Only places near here: latitude.
nearby_longitudenumberin query
Only places near here: longitude.
nearby_radiusintegerin query
How near, in metres. The nearest come first. At least 0. 20000 unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be

Request

curl "https://api.example.org/locations/"

const response = await fetch('https://api.example.org/locations/', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/locations/",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "address": "string",
      "alias": "string",
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "city": "string",
      "country": "string",
      "id": 42,
      "latitude": 1.5,
      "longitude": 1.5,
      "name": "string",
      "postal_code": "string",
      "profiles": 1,
      "state_province": "string",
      "type": "string"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Add a location

POST/locations/

It needs a point: one given (latitude, longitude), placed on a map, or an address to find it by. The address is optional, since a beach or a trail has none. Answers with the location.

Who: An administrator, with taxonomy:write

Body application/x-www-form-urlencoded or multipart/form-data

addressstring
Its street address, where it has one: a beach or a trail has none. At most 255 characters.
citystring
Its city. At most 100 characters.
countrystring
Its country. At most 50 characters.
latitudestring
Its point, where somebody placed it on a map: both, or neither. A point given is kept as it is; without one, the address is looked up.
longitudestring
namestringrequired
What it is called. At most 100 characters.
postal_codestring
Its postal or zip code. At most 15 characters.
source_idinteger
A post to tie to it at once: the post's id.
state_provincestring
Its state or province. At most 100 characters.

Answers

201
Created
location.LocationNodeItem application/json
400
not well formed, or the address could not be found on a map
401
no token, or one that has expired
403
the viewer may not do this

Request

curl -X POST "https://api.example.org/locations/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "address=string" \
  --data-urlencode "city=string" \
  --data-urlencode "country=string" \
  --data-urlencode "latitude=string" \
  --data-urlencode "longitude=string" \
  --data-urlencode "name=string" \
  --data-urlencode "postal_code=string" \
  --data-urlencode "source_id=42" \
  --data-urlencode "state_province=string"

const form = new URLSearchParams();
form.append('address', "string");
form.append('city', "string");
form.append('country', "string");
form.append('latitude', "string");
form.append('longitude', "string");
form.append('name', "string");
form.append('postal_code', "string");
form.append('source_id', "42");
form.append('state_province', "string");
const response = await fetch('https://api.example.org/locations/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/locations/",
    headers={"Authorization": f"Bearer {token}"},
    data={"address": "string", "city": "string", "country": "string", "latitude": "string", "longitude": "string", "name": "string", "postal_code": "string", "source_id": "42", "state_province": "string"},
)
answer = response.json()

Answer · 201

{
  "address": "string",
  "alias": "string",
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "city": "string",
  "country": "string",
  "id": 42,
  "latitude": 1.5,
  "longitude": 1.5,
  "name": "string",
  "postal_code": "string",
  "profiles": 1,
  "state_province": "string",
  "type": "string"
}

Locations used most of all

GET/locations/_browse/ordered_by_degree

Who: Anyone, signed in or not

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be

Request

curl "https://api.example.org/locations/_browse/ordered_by_degree"

const response = await fetch('https://api.example.org/locations/_browse/ordered_by_degree', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/locations/_browse/ordered_by_degree",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "address": "string",
      "alias": "string",
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "city": "string",
      "country": "string",
      "id": 42,
      "latitude": 1.5,
      "longitude": 1.5,
      "name": "string",
      "postal_code": "string",
      "profiles": 1,
      "state_province": "string",
      "type": "string"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Locations used most lately

GET/locations/_browse/trending

The locations the most profiles used in a window of time that ends now: the writers of public posts tied to it, by when they were written, and the public profiles (people, groups, events, websites) tagged with it, by when they were tagged; each profile once, whatever its kind, here or elsewhere; profiles says how many. time_window left out, the installation's own (TRENDING_WINDOW; daily where it federates, monthly where not), widened while it holds fewer than ten; window says which. One page, all there is: up to limit.

Who: Anyone, signed in or not

Parameters

limitintegerin query
The most to send. At least 0. 20 unless given.
time_windowstringin query
Asked for in lower case and told to the graph in upper case, as its constants are. "all" was accepted and never understood: the graph fell back to a day for anything it did not know. One of daily, weekly, monthly, yearly.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be

Request

curl "https://api.example.org/locations/_browse/trending"

const response = await fetch('https://api.example.org/locations/_browse/trending', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/locations/_browse/trending",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "address": "string",
      "alias": "string",
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "city": "string",
      "country": "string",
      "id": 42,
      "latitude": 1.5,
      "longitude": 1.5,
      "name": "string",
      "postal_code": "string",
      "profiles": 1,
      "state_province": "string",
      "type": "string"
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  },
  "window": "string"
}

One location

GET/locations/{id}

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
The location's id.

Answers

200
OK
location.LocationNodeItem application/json
400
the request is not well formed, or a value in it is not one it may be
404
there is no such location

Request

curl "https://api.example.org/locations/<id>"

const response = await fetch('https://api.example.org/locations/<id>', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/locations/<id>",
)
answer = response.json()

Answer · 200

{
  "address": "string",
  "alias": "string",
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "city": "string",
  "country": "string",
  "id": 42,
  "latitude": 1.5,
  "longitude": 1.5,
  "name": "string",
  "postal_code": "string",
  "profiles": 1,
  "state_province": "string",
  "type": "string"
}

Change a location

PATCH/locations/{id}

A point given (latitude, longitude) is kept as it is; without one, a changed address is found on the map again, and clearing the address keeps the point. Answers with the location.

Who: An administrator, with taxonomy:write

Parameters

idintegerrequiredin path
The location's id.

Body application/x-www-form-urlencoded or multipart/form-data

addressstring
Its street address, where it has one: a beach or a trail has none. At most 255 characters.
citystring
Its city. At most 100 characters.
countrystring
Its country. At most 50 characters.
latitudestring
Its point, where somebody placed it on a map: both, or neither. A point given is kept as it is; without one, the address is looked up.
longitudestring
namestringrequired
What it is called. At most 100 characters.
postal_codestring
Its postal or zip code. At most 15 characters.
state_provincestring
Its state or province. At most 100 characters.

Answers

200
OK
location.LocationNodeItem application/json
400
not well formed, or the address could not be found on a map
401
no token, or one that has expired
403
the viewer may not do this
404
there is no such location

Request

curl -X PATCH "https://api.example.org/locations/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "address=string" \
  --data-urlencode "city=string" \
  --data-urlencode "country=string" \
  --data-urlencode "latitude=string" \
  --data-urlencode "longitude=string" \
  --data-urlencode "name=string" \
  --data-urlencode "postal_code=string" \
  --data-urlencode "state_province=string"

const form = new URLSearchParams();
form.append('address', "string");
form.append('city', "string");
form.append('country', "string");
form.append('latitude', "string");
form.append('longitude', "string");
form.append('name', "string");
form.append('postal_code', "string");
form.append('state_province', "string");
const response = await fetch('https://api.example.org/locations/<id>', {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.patch(
    "https://api.example.org/locations/<id>",
    headers={"Authorization": f"Bearer {token}"},
    data={"address": "string", "city": "string", "country": "string", "latitude": "string", "longitude": "string", "name": "string", "postal_code": "string", "state_province": "string"},
)
answer = response.json()

Answer · 200

{
  "address": "string",
  "alias": "string",
  "authorized": {
    "add_follower": false,
    "administration": false,
    "audiences": [
      "string"
    ],
    "block_from_owner": false,
    "comment": false,
    "composers": [
      "string"
    ],
    "delete": false,
    "download": false,
    "edit": false,
    "hide": false,
    "invite": false,
    "like": false,
    "pin": false,
    "quote": false
  },
  "city": "string",
  "country": "string",
  "id": 42,
  "latitude": 1.5,
  "longitude": 1.5,
  "name": "string",
  "postal_code": "string",
  "profiles": 1,
  "state_province": "string",
  "type": "string"
}

Delete a location

DELETE/locations/{id}

Who: An administrator, with taxonomy:write

Parameters

idintegerrequiredin path
The location's id.

Answers

200
it is gone
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not do this
404
there is no such location

Request

curl -X DELETE "https://api.example.org/locations/<id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/locations/<id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/locations/<id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

The posts tied to a location

GET/locations/{id}/inbounds

Those the viewer may see.

Who: Anyone, signed in or not

Parameters

idintegerrequiredin path
What the posts are tied to: a hashtag's or a place's id.
startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
sortstringin query
The order they come in: recent, newest first, or relevant, what people have found useful lately, as search's Most relevant ranks it. At most 10 characters. One of created_at, updated_at, recent, popular, relevant. recent unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be
404
there is no such location

Request

curl "https://api.example.org/locations/<id>/inbounds"

const response = await fetch('https://api.example.org/locations/<id>/inbounds', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/locations/<id>/inbounds",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "avatar_urls": {
        "key": null
      },
      "body": "string",
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "editor": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "event": {
        "address": null,
        "cancelled_at": null,
        "capacity": null,
        "ends_at": null,
        "going_count": null,
        "has_address": null,
        "has_online_url": null,
        "host": null,
        "is_full": null,
        "maybe_count": null,
        "online_url": null,
        "open_to_host_followers": null,
        "starts_at": null,
        "state": null,
        "timezone_name": null,
        "viewer_rsvp": null
      },
      "feed": {
        "definition": null,
        "icon": null
      },
      "files": [
        null
      ],
      "follower_count": 1,
      "id": 42,
      "is_admined_by_viewer": false,
      "is_blocked_by_viewer": false,
      "is_following_viewer": false,
      "is_leading_viewer": false,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "name": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent": {
        "access": null,
        "alias": null,
        "author": null,
        "authorized": null,
        "body": null,
        "content": null,
        "cover_urls": null,
        "created_at": null,
        "files": null,
        "id": null,
        "is_liked_by_viewer": null,
        "is_reposted_by_viewer": null,
        "is_saved_by_viewer": null,
        "link_preview": null,
        "name": null,
        "owner": null,
        "portrait_urls": null,
        "title": null,
        "type": null,
        "video": null
      },
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root": {
        "access": null,
        "alias": null,
        "author": null,
        "authorized": null,
        "body": null,
        "content": null,
        "cover_urls": null,
        "created_at": null,
        "files": null,
        "id": null,
        "is_liked_by_viewer": null,
        "is_reposted_by_viewer": null,
        "is_saved_by_viewer": null,
        "link_preview": null,
        "name": null,
        "owner": null,
        "portrait_urls": null,
        "title": null,
        "type": null,
        "video": null
      },
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "verified": false,
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

Tie a post to a location

POST/locations/{id}/inbounds/

For the post's author, the owner of the profile it is on, and site administrators.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The id of the hashtag or the place.

Body application/x-www-form-urlencoded or multipart/form-data

source_idintegerrequired
The id of the post to tie to it.

Answers

201
tied, or tied already
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change the post
404
there is no such location or post
422
too_many_locations: the post is tied to five locations already
Refusal application/json

Request

curl -X POST "https://api.example.org/locations/<id>/inbounds/" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "source_id=42"

const form = new URLSearchParams();
form.append('source_id', "42");
const response = await fetch('https://api.example.org/locations/<id>/inbounds/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/locations/<id>/inbounds/",
    headers={"Authorization": f"Bearer {token}"},
    data={"source_id": "42"},
)
answer = response.json()

Untie a post from a location

DELETE/locations/{id}/inbounds/{source_id}

For the post's author, the owner of the profile it is on, and site administrators.

Who: Somebody signed in, with media:write

Parameters

idintegerrequiredin path
The id of the hashtag or the place.
source_idintegerrequiredin path
The id of the post to untie from it.

Answers

200
untied
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
403
the viewer may not change the post
404
there is no such location or post

Request

curl -X DELETE "https://api.example.org/locations/<id>/inbounds/<source_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/locations/<id>/inbounds/<source_id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/locations/<id>/inbounds/<source_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Written by Claude, reviewed by Rastin Mehr · About this