# info.description
Acceslibre is exposing a public [API](https://en.wikipedia.org/wiki/API)
allowing to programmatically query its database. This API embraces the
[REST paradigm](https://en.wikipedia.org/wiki/Representational_state_transfer) as much as possible and
exposes results in [JSON](https://en.wikipedia.org/wiki/JavaScript_Object_Notation), [geoJSON](https://en.wikipedia.org/wiki/GeoJSON), or [XML](https://en.wikipedia.org/wiki/XML) format.

The API root entry point can be accessed at
[`https://acceslibre.beta.gouv.fr/api/`](https://acceslibre.beta.gouv.fr/api/):
- An HTML view is presented when requested through a web browser,
- A response of type `application/json` is returned by default.
- A response of type `application/geo+json` is returned if explicitly requested by the client and if available.
- A response of type `application/xml` is returned if explicitly requested by the client and if available.
## Identification

If you want to use our API, we can provide you with a key, to attach to each request to the API via the following header:
```
Authorization: Api-Key <YOUR_API_KEY>
```

To request your API key, [contact us](https://acceslibre.beta.gouv.fr/contact/api_key), we have no reason to refuse :-)
If you plan to do some insertions and/or updates, during your developments, we are highly recommanding to use our `staging` platform (dedicated API key).

## Limitation

In order to guarantee the availability of the API for everyone, a maximum number of requests per second is defined.
If you reach this limit, an `HTTP 429 (Too many requests)` will be responded, inviting you to reduce the frequency and number of your requests.

## Business rules

- It is only possible to modify the accessibility data of an ERP via the API, the information on the ERP cannot be modified.
- It is only possible to enrich the data, it is not possible to delete any data (an element with a `true` or `false` value cannot go to `null`).

## Some examples of use

### Search for establishments with the name containing or being close to `piscine`, in Villeurbanne:

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/erps/?q=piscine&commune=Villeurbanne -H "Authorization: Api-Key <YOUR_API_KEY>"
```

Note that each result exposes a `url` key, which is a retrieval point for the establishment detail page.
This URL can also be dynamically constructed from the establishment UUID: `https://acceslibre.beta.gouv.fr/uuid/<establishment_uuid>/`


### Search for establishments contained in a box encompassing Valence (France) and retrieve them in geoJSON format in order to display them on a map:

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/erps/?zone=4.849022,44.885530,4.982661,44.963994 -H "accept: application/geo+json" -H "Authorization: Api-Key <YOUR_API_KEY>"
```

Note that the box is defined by 2 coordinates:
- min longitude, min latitude
- max longitude, max latitude

Also note that you can combine the filters (`code_postal`, `q`, `commune`, ...) and the geospatial search described here.

---

### Retrieve details of a given establishment

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/erps/piscine-des-gratte-ciel-2/ -H "Authorization: Api-Key <YOUR_API_KEY>"
```

Note the presence of the `accessibility` key which exposes the URL of the accessibility data retrieval point for this establishment.

---

### Retrieve accessibility details for this ERP

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/accessibility/<OBJECT_ID>/ -H "Authorization: Api-Key <YOUR_API_KEY>"
```

---

### Retrieve accessibility details for this ERP in readable and accessible format

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/accessibility/<OBJECT_ID>/?readable=true -H "Authorization: Api-Key <YOUR_API_KEY>"
```

---

### Edit accessibility details of an ERP

```
$ curl -X PATCH https://acceslibre.beta.gouv.fr/api/erps/<SLUG_DE_L_ERP>/ -H 'Content-Type: application/json' -H 'Authorization: Api-Key <YOUR_API_KEY>' -d '{"accessibility" : {"transport_station_presence": "true"}}'
```

---

### Retrieve sentences from an ERP widget

Note: you can also use the ASP_ID instead of the ERP slug.

```
$ curl -X GET https://acceslibre.beta.gouv.fr/api/erps/<SLUG_DE_L_ERP>/widget/ -H "Authorization: Api-Key <YOUR_API_KEY>"
# or
$ curl -X GET https://acceslibre.beta.gouv.fr/api/erps/<ASP_ID>/widget/ -H "Authorization: Api-Key <YOUR_API_KEY>"
```

---

Below you will find the exhaustive technical documentation of the entry points exposed by the API.

# paths./api/accessibilite/.get.description
This endpoint lists the establishments' **accessibility data**.

# paths./api/accessibilite/.get.parameters[].description
Un numéro de page de l'ensemble des résultats.

# paths./api/accessibilite/.get.parameters[].description
Nombre de résultats à retourner par page.

# paths./api/accessibilite/.get.parameters[].description
Render a human readable version of accessibility data

# paths./api/accessibilite/help/.get.description
Documente les différents champs d'accessibilité, spécifiant pour chacun :
- Le libellé du champ
- La documentation du champ

# paths./api/accessibilite/{id}/.get.description
This endpoint allows to retrieve accessibility data of a given establishment, identified by its ID.

# paths./api/accessibilite/{id}/.get.parameters[].description
Un(une) valeur entière unique identifiant ce(cette) Accessibilité.

# paths./api/activites/.get.description
This endpoint lists the **establishments activities**. It supports following filters:

- `?commune=Lyon` lists activities of all establishments in the city of *Lyon*

# paths./api/activites/.get.parameters[].description
Un numéro de page de l'ensemble des résultats.

# paths./api/activites/{slug}/.get.description
This endpoint is here to retrieve info about a given **establishment activity**,
identified by its [URL slug](https://en.wikipedia.org/wiki/Slug_(publishing))
(*slug*).

# paths./api/erps/.get.description
This endpoint lists the establishments (ERPs). It supports the following filters:

- `?q=impôts` search the establishments containing the *impôts* term in their name or activity
- `?commune=Lyon` returns establishments in *Lyon* city
- `?activite=administration-publique` returns the establishments having *Administration publique* as activity
- `?q=impôts&commune=Lyon&activite=administration-publique` returns *administrations publiques* establishments containing
  *impôts* term and located in the city of *Lyon*. You can also filter by city to have more precise results, by using `code_postal` or `code_insee` fields.
- `?source=gendarmerie&source_id=1002326` returns a record identified by its `source` and `source_id`.
- `?source=sp&asp_id=00033429-1b83-46b4-9101-3a2ad178af79` allows to search for an establishment by its Service Public ID (ASP_ID).
- `?uuid=d8823070-f999-4992-92e9-688be87a76a6` allows to search for an establishment idendified by its [unique OpenData identifier](https://schema.data.gouv.fr/MTES-MCT/acceslibre-schema/latest/documentation.html#propri%C3%A9t%C3%A9-id).

# paths./api/erps/.get.parameters[].description
Un numéro de page de l'ensemble des résultats.

# paths./api/erps/.get.parameters[].description
Nombre de résultats à retourner par page.

# paths./api/erps/.get.parameters[].description
Quel champ utiliser pour classer les résultats.

# paths./api/erps/.get.parameters[].description
Unique ASP ID provided by Service Public

# paths./api/erps/.get.parameters[].description
A true value will return only establishment having an ASP ID

# paths./api/erps/.get.parameters[].description
Geo area, following format `latitude,longitude` (for ex. `?around=45.76,4.83`)

# paths./api/erps/.get.parameters[].description
A true value will drop null or non filled accessibilities values.

# paths./api/erps/.get.parameters[].description
A true value will render a human readable version of accessibilities data.

# paths./api/erps/.get.parameters[].description
A true value will also return establishments which are in a draft state (non published).

# paths./api/erps/.get.parameters[].description
Filter establishments which have been created or updated during the last X days.

# paths./api/erps/.post.description
This endpoint is used to create an establishment, for an existing activity, identified by its [slug](https://en.wikipedia.org/wiki/Slug_(publishing))
(*slug*) having accessibility data.

# paths./api/erps/{slug}/.get.description
This endpoint returns data for a given establishment identified by its [slug](https://en.wikipedia.org/wiki/Slug_(publishing))
(*slug*).

# paths./api/erps/{slug}/.get.parameters[].description
Quel champ utiliser pour classer les résultats.

# paths./api/erps/{slug}/.patch.parameters[].description
Quel champ utiliser pour classer les résultats.

# components.schemas.Erp.properties.geom.description
Géolocalisation (carte rafraîchie une fois l'enregistrement sauvegardé)

# components.schemas.Erp.properties.siret.description
Numéro SIRET si l'ERP est une entreprise

# components.schemas.Erp.properties.contact_email.description
Adresse email permettant de contacter l'ERP

# components.schemas.Erp.properties.contact_url.description
Lien hypertexte permettant de contacter l'établissement (formulaire, chatbot, etc.)

# components.schemas.Erp.properties.source_id.description
Identifiant de l'ERP dans la source initiale de données

# components.schemas.Erp.properties.asp_id.description
Identifiant de l'ERP dans la base Service Public

# components.schemas.Erp.properties.published.description
Statut de publication de cet ERP: si la case est décochée, l'ERP ne sera pas listé publiquement

# components.schemas.Erp.properties.sources.items.properties.source.description
Nom de la source de données dont est issu cet ERP

# components.schemas.ErpImport.properties.numero.description
Numéro dans la voie, incluant le complément (BIS, TER, etc.)

# components.schemas.ErpImport.properties.siret.description
Numéro SIRET si l'ERP est une entreprise

# components.schemas.ErpImport.properties.contact_url.description
Lien hypertexte permettant de contacter l'établissement (formulaire, chatbot, etc.)

# components.schemas.ErpImport.properties.import_email.description
Adresse email permettant de relancer l'utilisateur lié à l'import de l'ERP

# components.schemas.ErpImport.properties.geoloc_provider.description
Indique le fournisseur utilisé pour la géolocalisation de l'adresse de l'ERP.

# components.schemas.ErpImport.properties.source.description
Nom de la source de données dont est issu cet ERP

# components.schemas.ErpImport.properties.source_id.description
Identifiant de l'ERP dans la source initiale de données

# components.schemas.ErpImport.properties.asp_id.description
Identifiant de l'ERP dans la base Service Public

# components.schemas.ErpImport.properties.sources.items.properties.source.description
Nom de la source de données dont est issu cet ERP