Version 3

INTRODUCTION

Census Code API is an API that allows a user to get a Census Code using a Postal Code and an address.

The domain of the current version is only for Spanish Census Code.

TABLE OF CONTENTS

In this documentation you will find:

• Getting Started
• Authentication
• Status and errors
• Examples
• Additional references
• Support
• Terms and conditions

CONCEPTS

Census Code

Census Code is a code corresponding to the minimal territorial municipality unit. This unit could be even smaller than a neighbourhood (for example, in big cities like Madrid or Barcelona). It usually contains between 1000 and 2500 inhabitants (except in the case that the municipality is smaller) and it is used for statistical purposes and to organize the electoral processes.

In the case of Spain, that it is the basis for this API, the Census Code is depending on the Statistical National Institute (Instituto Nacional de Estadística - INE, in Spanish).

Graphical example (this one is corresponding to the Servizurich area in Barcelona):

Census Structure

The structure of the Census Code is the following (numbers are the number of digits on the Census Code):

ProvinceCode(2 digits) - MunicipalityCode(3 digits) - DistrictCode(2 digits) - Section(3 digits)"

For example: "0801910060" is

As it was commented before, this information could be extracted from INE's information related to Census Codes.

Link to Common Getting Started Page

Link to Common Authentication Page

Depending on the values introduced (and with the requirement that the user has a valid token to request the service), there are different responses that the user can receive:

Status 200 : Ok

When the parameters are correct, the user receives a response with status 200 and a Census Code

The Census Code on the response could be more or less accurate depending on the parameters precision. It can happen different cases:

• The name of the street is incorrect. In this case the Census Code received is based in the Postal Code.
• The number of the street is empty. It is more accurate than the previous one, but in case the street is long enough to have different Census Codes (and probably different Postal Codes too), the response will be based also on the Postal Code.
• Postal Code is incorrect. Possibly the less accurate case. Postal Code and Census Code are sharing the Province Code (have a look on Census Code concept)
• The parameters provided are accurated and the response will be too.

Status 400 : Bad Request

Some of the mandatory parameters have been not filled up by the user.

Remember, mandatory parameters are "PostalCode" and "Street" and they could not be empty.

On this example, it is missed the "Street" parameter:

Status 401 : Access Denied

Request will be refused if token provided on the header request is not correct. In this case, user should contact with DDC Department to obtain a valid token.

Status 500 : Internal Server Error

These are unexpected errors on the binaries of the service. If it happens, the user user should contact with DDC Department, to help resolve the reason that caused this response.

How to make a request using Postman

(Remember to visit the Getting Started and Authentication Sections to make sure you have all the necessary to execute this example)

• Open Postman application. If you don't have it, you can download here (it's free).
• Create a new request, clicking on the "+" tab button

• This service uses a GET method. Select this on the dropdown list of method on the left (Normally it is set with this value by default).

Insert this URL on the URL textbox ("Enter request URL"):

https://owl-apimanager-uat.azure-api.net/census-api/v0.1/census

• Set the mandatory parameters on the "Params" section. Remember that "Street" and "PostalCode" parameters are mandatory!

• Click on "Headers" tab and insert the Ocp-Apim-Subscription-Key.

• Click on button "Send"

• If the values of the parameters and the access key are correct, you will get a response from the service.

These are some additional references that could be useful:

• INE (Instituto Nacional de Estadística)
• Spanish Postal Codes
• Geodan Demo Census Code Map

CONTACT

If it is needed more information or support, contact with DDC Department

GET MORE INFORMATION

It is possible to get more information about Census Code in the links exposed on the Additional references.

FROM ANYPOINT

html a href link - spawns new ACM Asset window

Common Documentation

MD [] link - current Anypoint window replaced by ACM Asset page

Common Documentation

FROM ACM

html a href link - no link test only Common Documentation(Anypoint)

Common Documentation

MD [] link - spawns new ACM Asset window

Common Documentation

In Summary ACM will not process HTML Link, Anypoint can

From Anypoint

HTML a href link - Spawns New Anypoint Window for Asset page

Common Documentation

MD [] link - Jumps to Anypoint Asset page in same window

Common Documentation

From ACM

HTML a href link with new window instruction - title in black no link

Common Documentation

HTML a href link no new window instructions just title - title in black no link

Anypoint common asset page

URL only - URL Link in Blue and spawns Anypoint Asset Window

https://anypoint.mulesoft.com/exchange/e7d54e45-d3dc-4399-bdcd-16cbc65426a4/c4e-common-documentation/minor/1.0/pages/Getting%20Started/

MD [] link - Spawns Anypoint Asset window

Common Documentation

In Summary ACM does not support HTML links, so ACM Assets cannot be used

Proposal is:

• Create Common Documentation Asset in Exchange for documentation only
• Use standard MD linking for both Anypoint & ACM
• Anypoint will not spawn new window, unless right click to link to open in new window, so same as Anypoint navigation
• ACM will spawn a new Exchange window leaving the ACM window available

Common Documentation

Image and Video

In order to speed up your integration we prepared a Postman collection which you can download from this link.

SLAs

Availability

The service is provided as is and no availability SLAs are provided yet

Usage Constraints

The service might be limited to usage constraints.

Rate limits

The service might have rate limits due to security & usage policies

LEGAL AGREEMENTS

To the extent that the General Data Protection Regulation of the EU (GDPR) applies to our processing of your personal data (or other laws that include similar rights), you have several rights, of which we would like to inform you; the right to access your data, the right of data rectification (if your data is inaccurate), the right of erasure (if the retention of your data is no longer necessary in relation to the envisaged purpose of the processing), the right to restrict the data processing (e.g. if you contest the accuracy of your data that we process), the right to data portability and the right to lodge a complaint with the competent supervisory authority. At any time during which your data is processed by us, you can withdraw your consent to the processing by reaching out to Zurich and request the data deletion.