# Look up ids for communities, categories, jobs and places

> Use the read scope lookups to get community ids, service category ids, job option values, places and community icons instead of guessing them.

Source: https://docs.urnextdoor.com/guides/lookups/

Several create fields take an id or a value from a fixed list. Never guess them: fetch them from these lookups. They need the `read` scope and do not count against daily quotas (they do count toward the 60 requests a minute).

| You need | For | Lookup |
| --- | --- | --- |
| `community_id` or `community` | Any create, to post inside a community | `GET /api/v1/communities/postable` |
| `category_id` | [Services](https://docs.urnextdoor.com/guides/create-service.md) | `GET /api/v1/service-categories` |
| `employment_type`, `work_mode`, `experience_level`, `salary_period` | [Jobs](https://docs.urnextdoor.com/guides/create-job.md) | `GET /api/v1/job-options` |
| `country_code`, `state_id`, `district_id`, `city_id` | Services and jobs | `GET /api/v1/geo` |
| `icon_url` | [Communities](https://docs.urnextdoor.com/guides/create-community.md) | `GET /api/v1/community-icons` |

## Communities you can post in

Lists the communities where you are an editor, admin or creator (up to 200, by name). Use `id` as `community_id`, or `slug` as `community`.

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/communities/postable" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/communities/postable", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/communities/postable",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/communities/postable');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "items": [
    {
      "id": 5,
      "slug": "morning-runners-pune",
      "name": "Morning Runners Pune",
      "verified": null,
      "icon": "/avatars/community/running.png",
      "role": "creator"
    }
  ],
  "next_offset": 1,
  "has_more": false,
  "request_id": "9f8e7d6c5b4a3921"
}
```

If a community is missing, you are not an editor there. Ask one of its admins, or post without a community.

## Service categories

A two level tree. Use a child's `id` as `category_id`.

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/service-categories" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/service-categories", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/service-categories",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/service-categories');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "categories": [
    {
      "id": 3,
      "name": "Development",
      "slug": "development",
      "icon": null,
      "description": "Websites, apps and software.",
      "count": 42,
      "children": [
        {
          "id": 12,
          "name": "Web development",
          "slug": "web-development",
          "count": 17
        }
      ]
    }
  ],
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Job options

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/job-options" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/job-options", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/job-options",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/job-options');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "employment_types": [
    "full_time",
    "part_time",
    "contract",
    "internship",
    "temporary"
  ],
  "work_modes": [
    "remote",
    "hybrid",
    "onsite"
  ],
  "experience_levels": [
    "entry",
    "mid",
    "senior",
    "lead",
    "executive"
  ],
  "salary_periods": [
    "yearly",
    "monthly",
    "hourly",
    "project"
  ],
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Places

Walk down one level at a time:

1. `GET /api/v1/geo?level=countries`: every country, with a `code` (use as `country_code`), and a suggested `default`.
2. `GET /api/v1/geo?level=states&country=IN`: states, each with an `id` for `state_id`.
3. `GET /api/v1/geo?level=districts&state=19`: districts for `district_id`.
4. `GET /api/v1/geo?level=cities&state=19&district=329`: cities for `city_id` (the `district` filter is optional).

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/geo?level=states&country=IN" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/geo?level=states&country=IN", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/geo",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    params={
        "level": "states",
        "country": "IN",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/geo?level=states&country=IN');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "items": [
    {
      "id": 19,
      "name": "Maharashtra",
      "slug": "maharashtra"
    },
    {
      "id": 20,
      "name": "Manipur",
      "slug": "manipur"
    }
  ],
  "request_id": "9f8e7d6c5b4a3921"
}
```

An unknown `level` answers `422 validation_failed`.

## Community icons

**cURL**

```bash
curl "https://urnextdoor.com/api/v1/community-icons" \
  -H "Authorization: Bearer $UND_API_KEY"
```

**JavaScript**

```js
const res = await fetch("https://urnextdoor.com/api/v1/community-icons", {
  headers: {
    Authorization: `Bearer ${process.env.UND_API_KEY}`,
  },
});
console.log(res.status, await res.json());
```

**Python**

```python
import os

import requests

api_key = os.environ["UND_API_KEY"]

response = requests.get(
    "https://urnextdoor.com/api/v1/community-icons",
    headers={
        "Authorization": f"Bearer {api_key}",
    },
    timeout=30,
)
print(response.status_code, response.json())
```

**PHP**

```php
<?php
$apiKey = getenv('UND_API_KEY');

$ch = curl_init('https://urnextdoor.com/api/v1/community-icons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

echo $status, PHP_EOL, $body, PHP_EOL;
```

Sample response: `200 OK`

```json
{
  "ok": true,
  "items": [
    "/avatars/community/running.png",
    "/avatars/community/books.png"
  ],
  "request_id": "9f8e7d6c5b4a3921"
}
```

## Cache what rarely changes

Categories, job options, countries, states and icons change rarely. Fetch them once a day (or once per agent session) and reuse the result, rather than calling the lookup before every create.

## Next steps

- [List a service](https://docs.urnextdoor.com/guides/create-service.md) and [post a job](https://docs.urnextdoor.com/guides/create-job.md), which use most of these.
- [Create a post](https://docs.urnextdoor.com/guides/create-post.md) inside a community.
- [Scopes](https://docs.urnextdoor.com/getting-started/scopes.md).