# OpenStreetMap API

> OpenStreetMap returns coordinates, readable addresses, and place search results as a workflow and API.

Get address returns a readable address and place details for required coordinates, with optional detail level and language. Search places finds named places or kinds of places in a required city or area, with optional language and result count.

- Page: https://fous.com/tools/openstreetmap
- Handle: `@openstreetmap`
- Category: [Maps](https://fous.com/tools/category/maps)
- Source website: https://openstreetmap.org
- Last verified: Sep 29, 2026

## Methods

### Get address

Operation `get_address`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a readable address, place name, address parts and OpenStreetMap link for map coordinates. Choose address, street or city detail. Results reflect the nearest mapped feature, which may differ from a landmark at that point.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `detail` | string | no | `"street"` | Level of place to return, for example street; defaults to address. |
| `language` | string | no | `"French"` | Preferred language for names and addresses, for example French or fr; defaults to English. |
| `latitude` | number | yes | `48.8584` | Latitude in decimal degrees, for example 48.8584. |
| `longitude` | number | yes | `2.2945` | Longitude in decimal degrees, for example 2.2945. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "latitude",
    "longitude"
  ],
  "properties": {
    "detail": {
      "enum": [
        "address",
        "street",
        "city"
      ],
      "type": "string",
      "default": "address",
      "description": "Level of place to return, for example street; defaults to address.",
      "examples": [
        "street",
        "city"
      ]
    },
    "language": {
      "type": "string",
      "default": "English",
      "description": "Preferred language for names and addresses, for example French or fr; defaults to English.",
      "examples": [
        "French",
        "English"
      ]
    },
    "latitude": {
      "type": "number",
      "maximum": 90,
      "minimum": -90,
      "description": "Latitude in decimal degrees, for example 48.8584.",
      "examples": [
        48.8584,
        40.7484
      ]
    },
    "longitude": {
      "type": "number",
      "maximum": 180,
      "minimum": -180,
      "description": "Longitude in decimal degrees, for example 2.2945.",
      "examples": [
        2.2945,
        -73.9857
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "latitude": 48.8584,
      "longitude": 2.2945
    },
    {
      "detail": "street",
      "language": "French",
      "latitude": 48.8584,
      "longitude": 2.2945
    },
    {
      "detail": "city",
      "language": "English",
      "latitude": 40.7484,
      "longitude": -73.9857
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `city` | string or null | `"Paris"` | City or town. |
| `road` | string or null | `"Avenue Gustave Eiffel"` | Road or street name. |
| `type` | string or null | `"Elevator"` | Type of mapped place in words. |
| `country` | string or null | `"France"` | Country. |
| `postcode` | string or null | `"75007"` | Postal code. |
| `place_name` | string or null | `"Avenue Gustave Eiffel"` | Name of the mapped place, when available. |
| `full_address` | string | `"Avenue Gustave Eiffel, Quartier du Gros-Caillou, 7th Arrondissement, Paris, Ile-de-France, Metropolitan France, 75007, ` | The readable address. |
| `house_number` | string or null |  | Building or house number. |
| `neighbourhood` | string or null | `"Quartier du Gros-Caillou"` | Neighbourhood or quarter. |
| `osm_object_id` | integer or null | `308145252` | OpenStreetMap object ID. |
| `osm_object_type` | string or null | `"way"` | OpenStreetMap object type. |
| `state_or_region` | string or null | `"Ile-de-France"` | State or region. |
| `openstreetmap_link` | string | `"https://www.openstreetmap.org/way/308145252"` | Link to the place on OpenStreetMap. |

**Example input**

```json
{
  "latitude": 48.8584,
  "longitude": 2.2945
}
```

**Example output**

```json
{
  "city": "Paris",
  "road": "Avenue Gustave Eiffel",
  "type": "Elevator",
  "country": "France",
  "postcode": "75007",
  "place_name": null,
  "full_address": "Avenue Gustave Eiffel, Quartier du Gros-Caillou, 7th Arrondissement, Paris, Ile-de-France, Metropolitan France, 75007, France",
  "house_number": null,
  "neighbourhood": "Quartier du Gros-Caillou",
  "osm_object_id": 308145252,
  "osm_object_type": "way",
  "state_or_region": "Ile-de-France",
  "openstreetmap_link": "https://www.openstreetmap.org/way/308145252"
}
```

### Get coordinates

Operation `get_coordinates`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find map coordinates and address details for an address or place, with optional country restriction. Data © OpenStreetMap contributors.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `address` | string | yes | `"10 Downing Street, London"` | Street address, place, or landmark to locate; for example, 10 Downing Street, London. |
| `country` | string | no | `"France"` | Country name or two-letter country code to restrict the search; for example, France or FR. Leave blank for any country. |
| `max_results` | integer | no | `2` | Maximum matches to return, from 1 to 10; for example, 3. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "Street address, place, or landmark to locate; for example, 10 Downing Street, London.",
      "examples": [
        "10 Downing Street, London",
        "Eiffel Tower",
        "Paris"
      ]
    },
    "country": {
      "type": "string",
      "default": "",
      "description": "Country name or two-letter country code to restrict the search; for example, France or FR. Leave blank for any country.",
      "examples": [
        "France",
        "US"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 1,
      "maximum": 10,
      "minimum": 1,
      "description": "Maximum matches to return, from 1 to 10; for example, 3.",
      "x-fous-developer": true,
      "examples": [
        2,
        3
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "address": "10 Downing Street, London"
    },
    {
      "address": "Eiffel Tower",
      "country": "France",
      "max_results": 2
    },
    {
      "address": "Paris",
      "country": "US",
      "max_results": 3
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `matches` | array |  | Matching locations, best first. |
| `matches[].city` | string or null | `"City of Westminster"` | City or town, when available. |
| `matches[].road` | string or null | `"Downing Street"` | Street or road, when available. |
| `matches[].type` | string | `"government"` | Kind of place in words. |
| `matches[].country` | string or null | `"United Kingdom"` | Country name, when available. |
| `matches[].latitude` | number | `51.5034878` | Latitude in decimal degrees. |
| `matches[].postcode` | string or null | `"SW1A 2AA"` | Postal code, when available. |
| `matches[].longitude` | number | `-0.1276965` | Longitude in decimal degrees. |
| `matches[].bounding_box` | object or null |  | Bounding box in decimal degrees, when available. |
| `matches[].full_address` | string | `"10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2` | Full formatted address. |
| `matches[].house_number` | string or null | `"10"` | House number, when available. |
| `matches[].osm_object_id` | integer or null | `1879842` | OpenStreetMap object ID, when available. |
| `matches[].osm_object_type` | string or null | `"relation"` | OpenStreetMap object kind (node, way, or relation), when available. |
| `matches[].state_or_region` | string or null | `"England"` | State or region, when available. |
| `matches[].openstreetmap_url` | string | `"https://www.openstreetmap.org/relation/1879842"` | Link to the place on OpenStreetMap. |

**Example input**

```json
{
  "address": "10 Downing Street, London"
}
```

**Example output**

```json
{
  "matches": [
    {
      "city": "City of Westminster",
      "road": "Downing Street",
      "type": "government",
      "country": "United Kingdom",
      "latitude": 51.5034878,
      "postcode": "SW1A 2AA",
      "longitude": -0.1276965,
      "bounding_box": {
        "east": -0.1273088,
        "west": -0.1277991,
        "north": 51.5036913,
        "south": 51.5033074
      },
      "full_address": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom",
      "house_number": "10",
      "osm_object_id": 1879842,
      "osm_object_type": "relation",
      "state_or_region": "England",
      "openstreetmap_url": "https://www.openstreetmap.org/relation/1879842"
    }
  ]
}
```

### Search places

Operation `search_places`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find named places or kinds of places in a city or area, in search order. Results may be fewer than requested. Data © OpenStreetMap contributors (ODbL).

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `what` | string | yes | `"museum"` | Kind of place or name to find, for example museum or Starbucks. |
| `where` | string | yes | `"Vienna, Austria"` | City or area to search, for example Vienna, Austria. |
| `language` | string | no | `"en"` | Language for names and addresses, for example en or de. |
| `max_results` | integer | no | `20` | Maximum places to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "what",
    "where"
  ],
  "properties": {
    "what": {
      "type": "string",
      "minLength": 1,
      "description": "Kind of place or name to find, for example museum or Starbucks.",
      "examples": [
        "museum",
        "Starbucks",
        "pharmacy"
      ]
    },
    "where": {
      "type": "string",
      "minLength": 1,
      "description": "City or area to search, for example Vienna, Austria.",
      "examples": [
        "Vienna, Austria"
      ]
    },
    "language": {
      "type": "string",
      "default": "en",
      "description": "Language for names and addresses, for example en or de.",
      "examples": [
        "en"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum places to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        20,
        5,
        50
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "what": "museum",
      "where": "Vienna, Austria",
      "language": "en",
      "max_results": 20
    },
    {
      "what": "Starbucks",
      "where": "Vienna, Austria",
      "max_results": 5
    },
    {
      "what": "pharmacy",
      "where": "Vienna, Austria",
      "max_results": 50
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `places` | array |  | Matching places in search order. |
| `places[].name` | string or null | `"Virgilkapelle"` | Place name. |
| `places[].type` | string or null | `"museum"` | Kind of place in words. |
| `places[].osm_id` | integer or null | `388758689` | OpenStreetMap object ID. |
| `places[].latitude` | number | `48.2083315` | Latitude in decimal degrees. |
| `places[].osm_type` | string or null | `"way"` | OpenStreetMap object type. |
| `places[].longitude` | number | `16.3722708` | Longitude in decimal degrees. |
| `places[].full_address` | string or null | `"Virgilkapelle, Stephansplatz, Stubenviertel, Katastralgemeinde Innere Stadt, Innere Stadt, Vienna, 1010, Austria"` | Full address or location. |
| `places[].openstreetmap_link` | string or null | `"https://www.openstreetmap.org/way/388758689"` | Page for this place on OpenStreetMap. |

**Example input**

```json
{
  "what": "museum",
  "where": "Vienna, Austria",
  "language": "en",
  "max_results": 20
}
```

**Example output**

```json
{
  "places": [
    {
      "name": "Virgilkapelle",
      "type": "museum",
      "osm_id": 388758689,
      "latitude": 48.2083315,
      "osm_type": "way",
      "longitude": 16.3722708,
      "full_address": "Virgilkapelle, Stephansplatz, Stubenviertel, Katastralgemeinde Innere Stadt, Innere Stadt, Vienna, 1010, Austria",
      "openstreetmap_link": "https://www.openstreetmap.org/way/388758689"
    },
    {
      "name": "Treasure of St. Stephen's Cathedral",
      "type": "museum",
      "osm_id": 485310799,
      "latitude": 48.2086963,
      "osm_type": "way",
      "longitude": 16.3726951,
      "full_address": "Treasure of St. Stephen's Cathedral, Stephansplatz, Stubenviertel, Katastralgemeinde Innere Stadt, Innere Stadt, Vienna, 1010, Austria",
      "openstreetmap_link": "https://www.openstreetmap.org/way/485310799"
    },
    {
      "name": "Imperial Treasury",
      "type": "museum",
      "osm_id": 441696312,
      "latitude": 48.20674,
      "osm_type": "node",
      "longitude": 16.3658462,
      "full_address": "Imperial Treasury, Swiss Courtyard, Widmerviertel, Katastralgemeinde Innere Stadt, Innere Stadt, Vienna, 1010, Austria",
      "openstreetmap_link": "https://www.openstreetmap.org/node/441696312"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@openstreetmap",
  "visibility": "public",
  "operation": "get_address",
  "version": 1,
  "input": {
    "latitude": 48.8584,
    "longitude": 2.2945
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@openstreetmap\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_address\",\n  \"version\": 1,\n  \"input\": {\n    \"latitude\": 48.8584,\n    \"longitude\": 2.2945\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@openstreetmap",
  "visibility": "public",
  "operation": "get_address",
  "version": 1,
  "input": {
    "latitude": 48.8584,
    "longitude": 2.2945
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/openstreetmap`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_address`: Get address. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_coordinates`: Get coordinates. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_places`: Search places. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-openstreetmap https://api.fous.com/mcp/tools/openstreetmap --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Locate customer addresses on a map
- Convert map coordinates into readable addresses
- Find businesses or kinds of places in an area
- Retrieve place coordinates for location records
- Check mapped place details by address

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this OpenStreetMap tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a OpenStreetMap account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from openstreetmap.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### How can I find coordinates for an address?

Use Get coordinates with an address or place name; optionally restrict the search by country or set the maximum results.

### How do I get an address from map coordinates?

Use Get address with latitude and longitude; optionally choose the detail level and preferred language.

### How can I search for places in a city?

Use Search places with the kind or name of place and the city or area.

## Related

- [Google Maps API](https://fous.com/tools/google-maps.md): Google Maps returns nearby places, public place details, up to 100 public reviews, and up to three routes; transit options vary by departure time.
- [Zippopotam.us API](https://fous.com/tools/zippopotam-us.md): Zippopotam.us returns places, regions and coordinates for postal codes in supported countries, and finds postal codes, places and coordinates by town and region.
- [Open Charge Map API](https://fous.com/tools/open-charge-map.md): Public electric-vehicle charging location listings.
- [Yelp API](https://fous.com/tools/yelp.md): Yelp returns local business matches, public profiles, ratings and up to 60 publicly shown reviews; matches are unsponsored and Yelp-ordered, but later results may lack contact or location details.
- [Postcodes.io API](https://fous.com/tools/postcodes-io.md): Postcodes.io provides UK postcode, location and administrative information; nearby postcode results include distance and coordinates, while retired postcodes lack administrative details.
- [US Census Bureau API](https://fous.com/tools/us-census-bureau.md): US Census Bureau returns statistics from varying Census years, population estimates through July 1, and address geographies using Census vintages that may differ from representation.
- [Yellow Pages API](https://fous.com/tools/yellow-pages.md): Find local US businesses and their contact details on Yellow Pages.
- [Google Search API](https://fous.com/tools/google-search.md): Google Search returns public web, image, job, event, related-question, and autocomplete results in Google’s order, with answers and details when available; results may be fewer, omit information, or be empty.
- [All Maps tools](https://fous.com/tools/category/maps)